Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion modules/concept-docs/pages/analytics-for-sdk-users.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
= Analytics
:description: Parallel data management for complex queries over many records, using a familiar N1QL-like syntax.
:description: Parallel data management for complex queries over many records, using a familiar {sqlpp} syntax.
:page-topic-type: concept
:page-aliases: analytics,

Expand Down
12 changes: 6 additions & 6 deletions modules/concept-docs/pages/n1ql-query.adoc
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
= Query
= Querying with {sqlpp}
:description: Parallel data management for complex queries over many records, using a familiar SQL-like syntax.
:page-topic-type: concept
:page-aliases: ROOT:n1ql-query,ROOT:prepared-statements,ROOT:querying
Expand Down Expand Up @@ -139,7 +139,7 @@ If index-maintenance is running behind, the query waits for it to catch up.
* `request_plus`: Executes the query, requiring the indexes first to be updated to the timestamp of the current query-request.
If index-maintenance is running behind, the query waits for it to catch up.

For N1QL, the default consistency is `not_bounded`.
For {sqlpp}, the default consistency is `not_bounded`.
////
Consider the following snippet:

Expand Down Expand Up @@ -191,10 +191,10 @@ LINQ is a community project.
Although it works well with Couchbase, it is not part of the officially-supported product.

LINQ (Language Integrated Query), is a powerful way to guide you in building your statements:
you obtain Type safety and auto completion of relevant methods and N1QL clauses.
you obtain Type safety and auto completion of relevant methods and {sqlpp} clauses.
It implements https://msdn.microsoft.com/en-us/library/mt693024.aspx[Microsoft’s language integrated query extensions to the C# language],
and is similar to other LINQ providers like Linq2SQL, Entity Framework and NHibernate.
The difference is that it emits N1QL in place of SQL.
The difference is that it emits {sqlpp} in place of SQL.
If you have used any other LINQ provider, you will find its familiarity and consistency make it an easy transition.

_Linq2Couchbase_, the LINQ provider for the Couchbase .NET SDK, is a stand-alone project which depends on Couchbase .NET SDK
Expand All @@ -205,7 +205,7 @@ and can be found on https://www.nuget.org/packages/linq2Couchbase[NuGet] -- and
PM> Install-Package Linq2Couchbase
----

Once you have included the dependency, you can construct queries just like any other LINQ provider in a SQL-like fashion. Nearly all N1QL statements and functions are supported, for example:
Once you have included the dependency, you can construct queries just like any other LINQ provider in a SQL-like fashion. Nearly all {sqlpp} statements and functions are supported, for example:

* INNER, LEFT Outer, and Index JOINs
* Math and Date functions
Expand All @@ -214,6 +214,6 @@ Once you have included the dependency, you can construct queries just like any o
* META keyword, NEST and UNNEST
* Etc.

In addition to N1QL language features, Linq2Coucbase supports ORM features like Change-tracking, and mapping of JSON fields to keys and other POCO properties.
In addition to {sqlpp} language features, Linq2Coucbase supports ORM features like Change-tracking, and mapping of JSON fields to keys and other POCO properties.
The provider’s core object is the `BucketContext`, which is a Unit of Work (UoW) type object for performing querying and mutations on a per request basis.
////
2 changes: 1 addition & 1 deletion modules/hello-world/pages/sample-application.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=using]

== Sample App Backend

The https://github.com/couchbaselabs/{travel-sample-git-project}/tree/HEAD/try-cb-dotnet directory contains the `Startup.cs` entrypoint, and various `Models` and `Controllers` which contain functions for handling users, registration, and N1QL queries.
The https://github.com/couchbaselabs/{travel-sample-git-project}/tree/HEAD/try-cb-dotnet directory contains the `Startup.cs` entrypoint, and various `Models` and `Controllers` which contain functions for handling users, registration, and {sqlpp} (formerly NIQL) queries.


include::{version-common}@sdk:shared:partial$sample-application.adoc[tag=data-model]
Expand Down
2 changes: 1 addition & 1 deletion modules/hello-world/pages/webui-cli-access.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ You can access individual documents using the _command line_ and _web console_.
== Command-Line

You can access documents in Couchbase using command line interfaces.
You can use the `cbc` tool for simple document lookups by their IDs (or _keys_) and the xref:7.1@server:n1ql:n1ql-intro/cbq.adoc[cbq] tool to issue N1QL queries.
You can use the `cbc` tool for simple document lookups by their IDs (or _keys_) and the xref:7.1@server:n1ql:n1ql-intro/cbq.adoc[cbq] tool to issue {sqlpp} (formerly N1QL) queries.
This section will discuss the installation and usage of the `cbc` tool, and is targeted towards Linux and Mac OS X users.

NOTE: You can also use `cbc` on Windows by extracting the archive with libcouchbase.
Expand Down
4 changes: 2 additions & 2 deletions modules/howtos/pages/analytics-using-sdk.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
= Analytics
:description: Parallel data management for complex queries over many records, using a familiar N1QL-like syntax.
:description: Parallel data management for complex queries over many records, using a familiar {sqlpp} syntax.
:page-topic-type: howto
:page-edition: Enterprise Edition

Expand Down Expand Up @@ -277,6 +277,6 @@ include::devguide:example$dotnet/Analytics.cs[tag=handle-scope,indent=0]
////
== Additional Resources

To learn more about using N1QL for Analytics -- the first commercial implementation of SQL++ -- see our link:https://sqlplusplus-tutorial.couchbase.com[Tutorial Introduction to SQL++ for SQL users].
To learn more about using {sqlpp} for Analytics -- see our link:https://sqlplusplus-tutorial.couchbase.com[Tutorial Introduction to SQL++ for SQL users].

////
4 changes: 2 additions & 2 deletions modules/howtos/pages/encrypting-using-sdk.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -168,11 +168,11 @@ For compatibility with SDK 2, you can configure the `CryptoManager` to use the o
include::example$EncryptingUsingSdk.csx[tag=legacy_field_name_prefix,indent=0]
----

Alternatively, you can https://forums.couchbase.com/t/replacing-field-name-prefix/28786[rename the existing fields using a N1QL statement].
Alternatively, you can https://forums.couchbase.com/t/replacing-field-name-prefix/28786[rename the existing fields using a {sqlpp} statement] (formerly N1QL).

WARNING: In SDK 2, only top-level fields could be encrypted.
SDK 3 allows encrypting fields at any depth.
If you decide to rename the existing fields, make sure to do so _before_ writing any encrypted fields below the top level, otherwise it may be difficult to rename the nested fields using a generic N1QL statement.
If you decide to rename the existing fields, make sure to do so _before_ writing any encrypted fields below the top level, otherwise it may be difficult to rename the nested fields using a generic {sqlpp} statement.


[#configure-legacy-decrypters]
Expand Down
2 changes: 1 addition & 1 deletion modules/howtos/pages/error-handling.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -375,7 +375,7 @@ Please note that we do not provide any stability guarantees on the names and val
| Contains the clientContext set by the user in the request options.

| service
| Contains a map of service-specific properties (i.e. the opaque for key value, the statement for a N1QL query etc)
| Contains a map of service-specific properties (i.e. the opaque for key value, the statement for a query etc)

| timings
| Contains information like how long encoding, dispatch, total time etc. took in microseconds.
Expand Down
2 changes: 1 addition & 1 deletion modules/howtos/pages/kv-operations.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -223,4 +223,4 @@ Another way of increasing network performance is to _pipeline_ operations with x

As well as various xref:concept-docs:data-model.adoc[Formats] of JSON, Couchbase can work directly with xref:concept-docs:nonjson.adoc[arbitary bytes, or binary format].

Our xref:n1ql-queries-with-sdk.adoc[Query Engine] enables retrieval of information using the SQL-like syntax of N1QL.
Our xref:n1ql-queries-with-sdk.adoc[Query Engine] enables retrieval of information using the SQL-like syntax of {sqlpp} (formerly N1QL).
24 changes: 12 additions & 12 deletions modules/howtos/pages/n1ql-queries-with-sdk.adoc
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
= Query
:description: You can query for documents in Couchbase using the N1QL query language, a language based on SQL, but designed for structured and flexible JSON documents.
= {sqlpp} Queries from the SDK
:description: You can query for documents in Couchbase using the {sqlpp} query language, a language based on SQL, but designed for structured and flexible JSON documents.
:page-topic-type: howto
:page-aliases: n1ql-query
:page-pagination: full
Expand All @@ -12,13 +12,13 @@ Querying can solve typical programming tasks such as finding a user profile by e



Our query service uses N1QL, which will be fairly familiar to anyone who's used any dialect of SQL.
xref:#additional-resources[Further resources] for learning about N1QL are listed at the bottom of the page.
Before you get started you may wish to checkout the xref:server:n1ql:n1ql-language-reference/index.adoc[N1QL intro page], or just dive in with a query against xref:server:manage:manage-settings/install-sample-buckets.adoc[our travel sample data set].
Our query service uses {sqlpp} (formerly N1QL), which will be fairly familiar to anyone who's used any dialect of SQL.
xref:#additional-resources[Further resources] for learning about {sqlpp} are listed at the bottom of the page.
Before you get started you may wish to checkout the xref:server:n1ql:n1ql-language-reference/index.adoc[{sqlpp} intro page], or just dive in with a query against xref:server:manage:manage-settings/install-sample-buckets.adoc[our travel sample data set].
In this case, the one thing that you need to know is that in order to make a Bucket queryable, it must have at least one index defined.
You can define a _primary_ index on a bucket. When executing queries, if a suitable index is not found, the primary index will ensure that the query will be executed anyway (the primary index should not be used in production to prevent scanning of the whole bucket).

To execute N1QL, you can use xref:server:tools:query-workbench.adoc[Query Workbench] (or you can use the xref:server:tools:cbq-shell.adoc[cbq command line tool]).
To execute {sqlpp}, you can use xref:server:tools:query-workbench.adoc[Query Workbench] (or you can use the xref:server:tools:cbq-shell.adoc[cbq command line tool]).
Open it, and enter the following:

[source,n1ql]
Expand Down Expand Up @@ -127,7 +127,7 @@ The query service provides an array of options to customize your query. The foll

Setting a staleness parameter for queries, with `scan_consistency`, enables a tradeoff between latency and (eventual) consistency.

* A N1QL query using the default *Not Bounded* Scan Consistency will not wait for any indexes to finish updating before running the query and returning results, meaning that results are returned quickly, but the query will not return any documents that are yet to be indexed.
* A {sqlpp} query using the default *Not Bounded* Scan Consistency will not wait for any indexes to finish updating before running the query and returning results, meaning that results are returned quickly, but the query will not return any documents that are yet to be indexed.

.ScanConsistency (NotBounded)
[source,csharp,indent=0]
Expand Down Expand Up @@ -201,12 +201,12 @@ A complete list of `QueryOptions` can be found in the https://docs.couchbase.com

== Additional Resources

NOTE: N1QL is not the only query option in Couchbase.
NOTE: {sqlpp} is not the only query option in Couchbase.
Be sure to check that xref:concept-docs:data-services.adoc[your use case fits your selection of query service].

* For a deeper dive into N1QL from the SDK, refer to our xref:concept-docs:n1ql-query.adoc[N1QL SDK concept doc].
* The xref:7.1@server:n1ql:n1ql-language-reference/index.adoc[Server doc N1QL intro] introduces a complete guide to the N1QL language, including all of the latest additions.
* The http://query.pub.couchbase.com/tutorial/#1[N1QL interactive tutorial] is a good introduction to the basics of N1QL use.
* For a deeper dive into {sqlpp} from the SDK, refer to our xref:concept-docs:n1ql-query.adoc[{sqlpp} SDK concept doc].
* The xref:7.1@server:n1ql:n1ql-language-reference/index.adoc[Server doc {sqlpp} intro] introduces a complete guide to the {sqlpp} language, including all of the latest additions.
* The http://query.pub.couchbase.com/tutorial/#1[{sqlpp} interactive tutorial] is a good introduction to the basics of {sqlpp} use.
* For scaling up queries, be sure to xref:7.1@server:learn:services-and-indexes/indexes/index-replication.adoc[read up on Indexes].
* N1QL is for operational queries; for analytical workloads, read more on xref:concept-docs:http-services.adoc#long-running-queries-big-data[when to choose Analytics], our implementation of SQL++ available in the Enterprise Edition.
* The Query Service is for operational queries; for analytical workloads, read more on xref:concept-docs:http-services.adoc#long-running-queries-big-data[when to choose Analytics].

10 changes: 5 additions & 5 deletions modules/howtos/pages/subdocument-operations.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -23,11 +23,11 @@ While full-document retrievals retrieve the entire document and full document up

You should use Sub-Document operations when you are modifying only portions of a document, and full-document operations when the contents of a document is to change significantly.

IMPORTANT: The Sub-Document operations described on this page are for _Key-Value_ requests only: they are not related to Sub-Document N1QL queries.
(Sub-Document N1QL queries are explained in the section xref:n1ql-queries-with-sdk.adoc[Querying with N1QL].)
IMPORTANT: The Sub-Document operations described on this page are for _Key-Value_ requests only: they are not related to Sub-Document {sqlpp} (formerly N1QL) queries.
(Sub-Document {sqlpp} queries are explained in the section xref:n1ql-queries-with-sdk.adoc[Querying with {sqlpp}].)

In order to use Sub-Document operations you need to specify a _path_ indicating the location of the Sub-Document.
The _path_ follows <<Path syntax,N1QL syntax>>.
The _path_ follows <<Path syntax,{sqlpp} syntax>>.
Considering the document:

.customer123.json
Expand Down Expand Up @@ -341,7 +341,7 @@ When receiving a top-level error code, you should traverse the results of the co

== Path Syntax

Path syntax largely follows N1QL conventions: A path is divided into components, with each component referencing a specific _level_ in a document hierarchy.
Path syntax largely follows {sqlpp} conventions: A path is divided into components, with each component referencing a specific _level_ in a document hierarchy.
Components are separated by dots (`.`) in the case where the element left of the dot is a dictionary, or by brackets (`[n]`) where the element left of the bracket is an array and `n` is the index within the array.

As a special extension, you can indicate the _last element_ of an array by using an index of `-1`, for example to get the last element of the array in the document
Expand All @@ -365,7 +365,7 @@ For example:
must be referenced as `literal\"quote.array`.

If the path also has special path characters (i.e.
a dot or brackets) it may be escaped using N1QL escapes.
a dot or brackets) it may be escaped using {sqlpp} escapes.
Considering the document

[source,json]
Expand Down
2 changes: 1 addition & 1 deletion modules/howtos/pages/transcoders-nonjson.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ include::example$Transcoding.cs[tag=raw-json-decode,indent=0]
It is most common to store JSON with Couchbase.
However, it is possible to store non-JSON documents, such as raw binary data, perhaps using an concise binary encoding like https://msgpack.org[MessagePack] or https://cbor.io/[CBOR], in the Key-Value store.

NOTE: It's important to note that the Couchbase Data Platform includes multiple components other than the Key-Value store -- including N1QL and its indexes, FTS, analytics, and eventing -- and these are optimized for JSON and will either ignore or provide limited functionality with non-JSON documents.
NOTE: It's important to note that the Couchbase Data Platform includes multiple components other than the Key-Value store -- including Query and its indexes, FTS, Analytics, and Eventing -- and these are optimized for JSON and will either ignore or provide limited functionality with non-JSON documents.

Also note that some simple data types can be stored directly as JSON, without recourse to non-JSON transcoding.
A valid JSON document can be a simple integer (`42`), string (`"hello"`), array (`[1,2,3]`), boolean (`true`, `false`) and the JSON `null` value.
Expand Down
2 changes: 1 addition & 1 deletion modules/project-docs/pages/compatibility.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ AWS Amazon Graviton2, Apple M1 ARM processors, and ARMv8 on Ubuntu 20.04 (from S
| Developer Preview in 6.6, SDK 3.0
2+| Since 3.0.1

| Scope-Level N1QL Queries & all Collections features
| Scope-Level {sqlpp} (formerly N1QL) Queries & all Collections features
| Not Supported
2+| Since SDK 3.2.0

Expand Down
12 changes: 6 additions & 6 deletions modules/project-docs/pages/migrating-sdk-code-to-3.n.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Retrieval of the content of the document is accomplished through the `ContentAs(
Also, in most cases you do not need to check the result object returned as exceptions are thrown for most error conditions.
Check the API reference for details.

Compare this to a N1QL query:
Compare this to a {sqlpp} (formerly N1QL) query:

[source,csharp]
----
Expand Down Expand Up @@ -356,7 +356,7 @@ There have been changes made in the following areas:
CouchbaseException is the root of all Couchbase-specific exceptions thrown by the SDK, serving as a base exception for many more detailed exceptions.
Each `CouchbaseException` has an associated `ErrorContext` which is populated with as much information as possible and then dumped alongside the stack trace if an error happens.

Here is an example of the error context if a N1QL query is performed with an invalid syntax (i.e. `select 1= from`):
Here is an example of the error context if a {sqlpp} query is performed with an invalid syntax (i.e. `select 1= from`):

[source,csharp]
----
Expand Down Expand Up @@ -549,12 +549,12 @@ Similar functionality is available through `MutateIn` on JSON documents.

=== Query

N1QL querying is now available at the `Cluster` level instead of the bucket level, because you can also write N1QL queries that span multiple buckets.
{sqlpp} querying is now available at the `Cluster` level instead of the bucket level, because you can also write {sqlpp} queries that span multiple buckets.
Querying is now async by default as discussed earlier.
One related change is that query results come back in an async stream by default as well.
To convert results to IEnumerable to iterate like you would in the 2.x SDK, you can call `.ToEnumerable()` on the results.

Compare a simple N1QL query from SDK 2 with its SDK 3 equivalent:
Compare a simple {sqlpp} query from SDK 2 with its SDK 3 equivalent:

[source,csharp]
----
Expand Down Expand Up @@ -672,7 +672,7 @@ Not only does it throw a `CouchbaseException`, it also tries to map it to a spec

=== Analytics

Analytics querying, like N1QL, is also moved to the `Cluster` level: it is now accessible through the `Cluster.AnalyticsQueryAsync` method.
Analytics querying, like {sqlpp}, is also moved to the `Cluster` level: it is now accessible through the `Cluster.AnalyticsQueryAsync` method.
As with the Query service, parameters for the Analytics queries have moved into the `AnalyticsOptions`:

[source,csharp]
Expand Down Expand Up @@ -830,7 +830,7 @@ Couchbase.Core.Exceptions.View.ViewNotFoundException: 'http://localhost:8092/def
In SDK 2, the management APIs were centralized in the `ClusterManager` at the cluster level and the `BucketManager` at the bucket level.
Since SDK 3 provides more management APIs, they have been split up in their respective domains.
So for example when in SDK 2 you needed to remove a bucket you would call `ClusterManager.removeBucket` you will now find it under `BucketManager.dropBucket`.
Also, creating a N1QL index now lives in the `QueryIndexManager`, which is accessible through the `Cluster`.
Also, creating a {sqlpp} index now lives in the `QueryIndexManager`, which is accessible through the `Cluster`.

The following table provides a mapping from the SDK 2 management APIs to those of SDK 3:

Expand Down
4 changes: 2 additions & 2 deletions modules/ref/pages/client-settings.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,7 @@ Cluster Options: `EnableMutationTokens(boolean)`
Default: `true`
+

Mutation tokens allow enhanced durability requirements as well as advanced N1QL querying capabilities.
Mutation tokens allow enhanced durability requirements as well as advanced {sqlpp} (formerly N1QL) querying capabilities.
Set this to `false` if you do not require these features and wish to avoid the associated overhead.

Name: *Socket Keepalive*::
Expand Down Expand Up @@ -373,7 +373,7 @@ Cluster Option: `QueryTimeout(TimeSpan)`
Default: `75s`
+

The Query timeout is used on all N1QL query operations if not overridden by a custom timeout.
The Query timeout is used on all {sqlpp} query operations if not overridden by a custom timeout.
Note that it is set to such a high timeout compared to key/value since it can affect hundreds or thousands of rows.

Name: *Search Timeout*::
Expand Down