Update product documentation to use SQL++ instead of N1QL (#383)

jeffrymorris · web-flow · commit 6b63364d4290 · 2024-11-14T15:38:42.000-08:00
diff --git a/README.md b/README.md
@@ -3,13 +3,15 @@
 [![Join the chat at https://gitter.im/couchbaselabs/Linq2Couchbase](https://badges.gitter.im/couchbaselabs/Linq2Couchbase.svg)](https://gitter.im/couchbaselabs/Linq2Couchbase?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 ![.NET Core](https://github.com/couchbaselabs/Linq2Couchbase/workflows/.NET%20Core/badge.svg)
 
-The official Language Integrated Query (LINQ) provider for querying Couchbase Server with [N1QL](https://docs.couchbase.com/server/current/n1ql/n1ql-intro/queriesandresults.html) using the Couchbase .NET SDK. The goal of Linq2Couchbase is to create a lightweight ORM/ODM for querying Couchbase Buckets using LINQ as the lingua-franca between your application and Couchbase Server using N1QL, a SQL-like query language for JSON documents. It also provides a write API for performing CRUD operations on JSON documents.
+The official Language Integrated Query (LINQ) provider for querying Couchbase Server with [SQL++](https://docs.couchbase.com/server/current/n1ql/n1ql-intro/queriesandresults.html) using the Couchbase .NET SDK. The goal of Linq2Couchbase is to create a lightweight ORM/ODM for querying Couchbase Buckets using LINQ as the lingua-franca between your application and Couchbase Server using SQL++, a SQL-like query language for JSON documents. It also provides a write API for performing CRUD operations on JSON documents.
 
 While not an officially supported Couchbase project, this repo is actively maintained and monitored. If you happen to find a bug or have any questions, please either create an [issue](https://github.com/couchbaselabs/linq2couchbase/issues) or make a post on [forums.couchbase.com](https://forums.couchbase.com/c/net-sdk). Additionally, we actively accept contributions!
 
-> :info: This documentation is for Linq2Couchbase 2.x, compatible with Couchbase SDK 3.x. For documentation on
+> [INFO] This documentation is for Linq2Couchbase 2.x, compatible with Couchbase SDK 3.x. For documentation on
 > Linq2Couchbase 1.x compatible with Couchbase SDK 2.x, see [the release14 branch](https://github.com/couchbaselabs/Linq2Couchbase/blob/release14/README.md).
 
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
 ## Getting started
 
 The Linq2Couchbase project has the following dependencies:
@@ -143,7 +145,7 @@ Linq2Couchbase uses the NuGet package manager for handling dependencies.  To bui
 
 ## Project management
 
-In the [Jira project for Linq2Couchbase](http://issues.couchbase.com/browse/LINQ), you can file bugs, propose features or get an idea for the roadmap there. There is also a [list of supported and proposed N1QL features for Linq2Couchbase](https://docs.google.com/document/d/1hPNZ-qTKpVzQsFwg_1uUueltzNL1wA75L5F-hYF92Cw/edit?usp=sharing).
+In the [Issues for Linq2Couchbase](https://github.com/couchbaselabs/Linq2Couchbase/issues), you can file bugs, propose features or get an idea for the roadmap there. There is also a [list of supported and proposed SQL++ features for Linq2Couchbase](https://docs.google.com/document/d/1hPNZ-qTKpVzQsFwg_1uUueltzNL1wA75L5F-hYF92Cw/edit?usp=sharing).
 
 ## Contributors
 
diff --git a/docs/any-all.md b/docs/any-all.md
@@ -1,5 +1,8 @@
 # Any and All
 
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
 The LINQ Any and All methods are a useful way to test for a condition across a series of documents.
 
 ## Any
diff --git a/docs/array-filtering-projections.md b/docs/array-filtering-projections.md
@@ -1,6 +1,9 @@
 # Array Filtering, Projections, and Sorting
 
-Using array filtering and projections, you can alter the nature of an array located inside a document before it is returned by N1QL.
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
+Using array filtering and projections, you can alter the nature of an array located inside a document before it is returned by SQL++.
 
 ## Filtering
 
diff --git a/docs/async-queries.md b/docs/async-queries.md
@@ -1,5 +1,8 @@
 # Asynchronous Queries
 
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
 For performance in high load web environments, Linq2Couchbase supports executing queries asynchronously. This helps optimize thread utilization by avoiding thread blocking during long running query operations.
 
 > :info: **Note:** The methods below will only work for Linq2Couchbase queries. Code completion will show them as an option for other types of LINQ queries, but they will fail when executed. Other libraries, such as Entity Framework Core, have their own versions of these methods designed for use with their queries.
diff --git a/docs/bucket-context.md b/docs/bucket-context.md
@@ -1,5 +1,8 @@
 # The BucketContext
 
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
 The public API for Linq2Couchbase is the BucketContext; this object is similar to the DbContext in Linq2SQL and the DataContext from the EntityFramework. It's primary purpose is to provide and interface for building and submitting queries to a Couchbase server Bucket. Internally, the BucketContext uses a Cluster object and CouchbaseBucket to handle communication and to send queries and updates to the server.
 
 ## Creating a BucketContext
diff --git a/docs/custom-serializers.md b/docs/custom-serializers.md
@@ -1,16 +1,19 @@
 # Custom JSON Serializers
 
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
 The Couchbase SDK uses Newtonsoft's Json.Net as its default JSON serializer.  If you are using a custom serializer, there are some special requirements which must be met to support Linq2Couchbase.
 
 Custom serializers are used by creating a class which implements the ITypeSerializer interface, and including it in the SDK configuration.  However, to support Linq2Couchbase, instead the serializer should extend IExtendedTypeSerializer.  This interface provides a key additional feature.
 
-The GetMemberName method is used to determine how a particular member property of a POCO will be written as JSON to the document in Couchbase.  This is important, because the N1QL query must reference member names in the way they appear in Couchbase, not the way they appear in your .Net POCOs.
+The GetMemberName method is used to determine how a particular member property of a POCO will be written as JSON to the document in Couchbase.  This is important, because the SQL++ query must reference member names in the way they appear in Couchbase, not the way they appear in your .Net POCOs.
 
 Here is [an example of how this method was implemented for Newtonsoft's Json.Net](https://github.com/couchbase/couchbase-net-client/blob/03d7957226da6f7c3e05220a21e7ebeeb0519b93/Src/Couchbase/Core/Serialization/DefaultSerializer.cs#L192).
 
 ## Non-standard conversions
 
-Some attributes may have additional decorators applied that change how they are serialized. To support this, you should also implement a customer `ISerializationConverterProvider`. This interface can return a custom `ISerializationConverter` for a particular member, altering query generation behavior when this member is used in a N1QL query.
+Some attributes may have additional decorators applied that change how they are serialized. To support this, you should also implement a customer `ISerializationConverterProvider`. This interface can return a custom `ISerializationConverter` for a particular member, altering query generation behavior when this member is used in a SQL++ query.
 
 ```cs
 services.AddCouchbase(options => {
diff --git a/docs/date-handling.md b/docs/date-handling.md
@@ -1,6 +1,9 @@
 # Date Handling
 
-LINQ works with dates under the assumption that they are stored in the JSON documents as [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) formatted strings. For more information about N1QL functions and date handling, see [Date functions](http://developer.couchbase.com/documentation/server/4.0/n1ql/n1ql-language-reference/datefun.html) in the N1QL language reference.
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
+LINQ works with dates under the assumption that they are stored in the JSON documents as [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) formatted strings. For more information about SQL++ functions and date handling, see [Date functions](http://developer.couchbase.com/documentation/server/4.0/n1ql/n1ql-language-reference/datefun.html) in the SQL++ language reference.
 
 Date/times stored as milliseconds since the Unix epoch are also supported. If you are using the default Newtonsoft.Json serializer, simply add the `[JsonConverter(typeof(UnixMillisecondsConverter)]` attribute to the property. For custom serializers, see [Custom JSON Serializers](./custom-serializers.md).
 
@@ -27,7 +30,7 @@ using (var cluster = new Cluster()) {
 
 ## Date Functions
 
-A subset of N1QL date/time functions are supported for use in LINQ queries, and are provided as static methods of the N1QlFunctions class.
+A subset of SQL++ date/time functions are supported for use in LINQ queries, and are provided as static methods of the N1QlFunctions class.
 
 ```cs
 using (var cluster = new Cluster()) {
@@ -46,7 +49,7 @@ using (var cluster = new Cluster()) {
 }
 ```
 
-| Function Name               | N1QL Equivalent |
+| Function Name               | SQL++ Equivalent |
 | --------------------------- | --------------- |
 | N1QlFunctions.DateDiff      | DATE_DIFF_STR   |
 | N1QlFunctions.DateAdd       | DATE_ADD_STR    |
diff --git a/docs/document-filters.md b/docs/document-filters.md
@@ -1,6 +1,9 @@
 # Mapping JSON documents to POCOs with DocumentFilters
 
-Couchbase allows you store heterogeneous documents within a Bucket or "keyspace". When you do a select without a predicate, you are querying across the entire keyspace. For example, imagine a bucket with various document "types" and you do a N1QL query like this:
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
+Couchbase allows you store heterogeneous documents within a Bucket or "keyspace". When you do a select without a predicate, you are querying across the entire keyspace. For example, imagine a bucket with various document "types" and you do a SQL++ query like this:
 
 ```sql
 SELECT name FROM `travel-sample`
@@ -74,7 +77,7 @@ public class Airline
 }
 ```
 
-Now when we generate a LINQ query, the `WHERE type="airline"` clause will be automatically added to the emitted N1QL query and only documents of type "airline" will be returned.
+Now when we generate a LINQ query, the `WHERE type="airline"` clause will be automatically added to the emitted SQL++ query and only documents of type "airline" will be returned.
 
 ## Custom Document Filters
 
diff --git a/docs/enum.md b/docs/enum.md
@@ -1,5 +1,8 @@
 # Working With Enumerations
 
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
 For the most part, enumeration properties are supported transparently.  LINQ queries can filter based on enumeration values just like other properties:
 
 ```cs
diff --git a/docs/grouping-aggregation.md b/docs/grouping-aggregation.md
@@ -1,5 +1,8 @@
 # Grouping and Aggregation
 
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
 LINQ may also be used to group query results and perform aggregation of data on the groupings. This grouping and aggregation is performed on the query server for improved performance.
 
 > :info: **Note:** LINQ group joins are not currently supported.
diff --git a/docs/joins.md b/docs/joins.md
@@ -1,5 +1,8 @@
 # Joining Documents
 
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
 Joins are used to combine multiple documents with a common link into a single query result. They work much like traditional joins in SQL, though there are some differences.
 
 > :info: **Note:** Joins can be performed across multiple buckets, so long as the buckets are all on the same cluster.
@@ -86,7 +89,7 @@ await foreach (var doc in query.AsAsyncEnumerable()) {
 
 ## ANSI Joins
 
-Beginning with Couchbase Server 5.5, N1QL supports full ANSI joins. It is possible to join against any properties on either side, without using N1QlFunctions.Key. It is necessary, however, to ensure there is an index which can be used to lookup the properties on the right-hand side.
+Beginning with Couchbase Server 5.5, SQL++ supports full ANSI joins. It is possible to join against any properties on either side, without using N1QlFunctions.Key. It is necessary, however, to ensure there is an index which can be used to lookup the properties on the right-hand side.
 
 ```cs
 var context = new BucketContext(bucket);
diff --git a/docs/math-functions.md b/docs/math-functions.md
@@ -1,6 +1,9 @@
 # Math Functions
 
-Most math functions from the .Net Math class are supported by N1QL.  They may be used anywhere in the query, including where predicates, select projections, and sort ordering.
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
+Most math functions from the .Net Math class are supported by SQL++.  They may be used anywhere in the query, including where predicates, select projections, and sort ordering.
 
 ## Supported Math Functions
 
diff --git a/docs/meta-keyword.md b/docs/meta-keyword.md
@@ -1,11 +1,14 @@
 # The META() function
 
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
 For every document Couchbase Server will also store another document containing the metadata describing that document. Metadata includes the following fields:
 
 - Id - the primary key for the document
 - CAS - Compare and Swap value
 - Flags - SDK specific type encoding (internal use only)
-- Type - the type of document stored in Couchbase (will always be JSON for N1QL)
+- Type - the type of document stored in Couchbase (will always be JSON for SQL++)
 
 There is additionally metadata stored within couchbase for each document (TTL and Sequence Number), but this is not available from the META function.
 
diff --git a/docs/nest.md b/docs/nest.md
@@ -1,5 +1,8 @@
 # Nesting Documents
 
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
 Nesting documents is somewhat similar to [Joining Documents](joins.md). It has some of the same behaviors and limitations.
 
 However, nesting returns the data in a different format. Nests expect the document on the left to have a list of document keys in an array. Each key on the document is then loaded from the bucket, and a array of documents is provided.  This array may then be manipulated and used elsewhere in the query, such as the select projection or where clause.
@@ -101,7 +104,7 @@ await foreach (var doc in query.AsAsyncEnumerable()) {
 
 ## ANSI Nests
 
-Beginning with Couchbase Server 5.5, N1QL supports full ANSI joins, including ANSI nests. It is now possible to nest against any properties on either side, the N1QlFunctions.Key limitation no longer applies.
+Beginning with Couchbase Server 5.5, SQL++ supports full ANSI joins, including ANSI nests. It is now possible to nest against any properties on either side, the N1QlFunctions.Key limitation no longer applies.
 
 To use this feature, simply perform a group join on the desired properties in LINQ. It is necessary, however, to ensure there is an index which can be used to lookup the properties on the right-hand side.
 
diff --git a/docs/null-missing-valued.md b/docs/null-missing-valued.md
@@ -1,6 +1,9 @@
 # Testing For NULL And MISSING Attributes
 
-Like SQL, N1QL allows you to test for NULL values in your queries. Additionally, N1QL adds the concept of MISSING, which means that the attribute isn't present in the document. NULL means that the attribute is present in the document, but set specifically to null.
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
+Like SQL, SQL++ allows you to test for NULL values in your queries. Additionally, SQL++ adds the concept of MISSING, which means that the attribute isn't present in the document. NULL means that the attribute is present in the document, but set specifically to null.
 
 ## Testing For NULL
 
@@ -52,7 +55,7 @@ This query will return all beers where there is an "abv" attribute present on th
 
 ## Testing For Valued Attributes
 
-Testing for null and missing are very specific tests. If you test for null, it returns false if the value is missing. If you test for missing, it returns false if the value is null. N1QL also provides the concept of an attribute being valued. This combines the two concepts, considering both nulls and missing values to be not valued. This is implemented in LINQ using N1QlFunctions.IsValued and N1QlFunctions.IsNotValued.
+Testing for null and missing are very specific tests. If you test for null, it returns false if the value is missing. If you test for missing, it returns false if the value is null. SQL++ also provides the concept of an attribute being valued. This combines the two concepts, considering both nulls and missing values to be not valued. This is implemented in LINQ using N1QlFunctions.IsValued and N1QlFunctions.IsNotValued.
 
 ```cs
 var context = new BucketContext(bucket);
diff --git a/docs/poco-mapping.md b/docs/poco-mapping.md
@@ -1,5 +1,8 @@
 # Mapping JSON fields to POCO properties
 
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
 While not an actually responsibility of the LINQ provider, the default serialization library, Newtonsoft.Json, supports field the following serialization attributes:
 
 - [DataContractAttribute](https://msdn.microsoft.com/en-us/library/ms585243)
diff --git a/docs/query-hints.md b/docs/query-hints.md
@@ -1,5 +1,8 @@
 # Query Hints
 
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
 ## UseIndex
 
 The UseIndex method is used to provide an index hint to the query engine.  This can help improve query performance in cases where Explain shows that the index being used by default is inefficient.
@@ -32,7 +35,7 @@ var query = from beer in context.Query<Beer>().UseIndex("beer_abv", N1QlIndexTyp
             select beer;
 ```
 
-Note that views must be defined using a `CREATE INDEX` statement in order to be usable via N1QL queries.
+Note that views must be defined using a `CREATE INDEX` statement in order to be usable via SQL++ queries.
 
 ## Hash Joins
 
diff --git a/docs/ryow.md b/docs/ryow.md
@@ -1,6 +1,9 @@
 # Using Read Your Own Write (RYOW)
 
-When writing changes (mutating documents), Couchbase Server indexes are not updated immediately. This allows improved write performance, because it isn't necessary for mutations to wait for index updates to complete before returning. This index update delay doesn't affect CRUD operations via the SDK, but it does affect the results returned by N1QL queries.
+> [NOTE]
+> The documetation has been updated to reflect that the product name for N1QL has been changed to SQL++, however, the source itself may still use the name N1QL.
+
+When writing changes (mutating documents), Couchbase Server indexes are not updated immediately. This allows improved write performance, because it isn't necessary for mutations to wait for index updates to complete before returning. This index update delay doesn't affect CRUD operations via the SDK, but it does affect the results returned by SQL++ queries.
 
 This delay is often unnoticed. However, there can be circumstances where you need to execute a query immediately following a mutation, and need the mutation to be included in the query result. For example, if you are posting a new sales order, and then query the total sales for that customer after posting the new order.
 
diff --git a/docs/serialization-converters.md b/docs/serialization-converters.md
diff --git a/docs/simple-select.md b/docs/simple-select.md
diff --git a/docs/sorting-take-limit.md b/docs/sorting-take-limit.md
diff --git a/docs/string-handling.md b/docs/string-handling.md
diff --git a/docs/unnest.md b/docs/unnest.md
diff --git a/docs/use-keys.md b/docs/use-keys.md
diff --git a/docs/where-clause.md b/docs/where-clause.md
