Skip to content

DOC-13726 add ide section #282

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Pallavi-Janardhan wants to merge 2 commits into
base: temp/4.6
Choose a base branch
from
Open

DOC-13726 add ide section #282

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0cdcdef
Including IDE Plugin information
Pallavi-Janardhan Dec 1, 2025
4ad6c93
Including IDE Plugin information_2nd_iteration
Pallavi-Janardhan Dec 1, 2025
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
87 changes: 44 additions & 43 deletions modules/hello-world/pages/start-using-sdk.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,11 +139,11 @@ If you intend to use `TypeScript` instead of `JavaScript`, then also do the foll
$ npm install -g typescript ts-node
----

// === IDE Plugins
//
// To make development easier, Couchbase plugins are available for VSCode and the IntelliJ family of IDEs and editors.
// For links and more information on these and other integrations across the {name_platform} ecosystem,
// check out the xref:project-docs:third-party-integrations.adoc[] page.
=== IDE Plugins

To make development easier, Couchbase plugins are available for VSCode and the IntelliJ family of IDEs and editors.
For links and more information about these and other integrations across the {name_platform} ecosystem,
check out the xref:project-docs:third-party-integrations.adoc[] page.

=== Grab the Code

Expand Down Expand Up @@ -178,11 +178,11 @@ Otherwise, read on as we introduce the CRUD API and connection to Capella or sel

TIP: There's a *View* link to the complete sample code on GitHub above each of the snippets on these SDK pages, and a *Copy* icon to grab just the snippet shown.

NOTE: The code samples on this page use ESModules, but the Node.js SDK is fully compatible with CommonJS as well. Simply adjust the import syntax as needed.
NOTE: The code samples on this page use ESModules, but the Node.js SDK is fully compatible with CommonJS as well. Specify the import syntax as needed.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whilst making a change here, it would also be a good idea to put in the line break for the new sentence. 👍


== Connect to your Database

Connect to your Couchbase Capella operational cluster (or your local Couchbase Cluster, if you are trying out self-managed Couchbase).
Connect to your Couchbase Capella operational cluster (or your local Couchbase Cluster, if you're trying out self-managed Couchbase).

[tabs]
====
Expand All @@ -194,7 +194,7 @@ Couchbase Capella (JavaScript)::
include::devguide:example$nodejs/capella_connection_crud.js[tag=connect,indent=0]
----

Note, the client certificate for connecting to a Capella cluster is included in the SDK installation.
NOTE: SDK installation includes the client certificate for connecting to a Capella cluster.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This could be interpreted as saying that the cert is brought in as part of the installation process,
rather than simply being included in the npm package.
Perhaps:
The SDK includes...

--

Couchbase Capella (Typescript)::
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Presuming you ran Vale - did it show up all of the places where Javascript should be JavaScript,
and Typescript should be TypeScript?
May as well add in these changes, too. 👍

Copy link
Author

@Pallavi-Janardhan Pallavi-Janardhan Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No it didnt show. I will search for it and change it everywhere.

Expand All @@ -205,7 +205,7 @@ Couchbase Capella (Typescript)::
include::devguide:example$nodejs/capella_connection_crud.ts[tag=connect,indent=0]
----

Note, the client certificate for connecting to a Capella cluster is included in the SDK installation.
NOTE: SDK installation includes the client certificate for connecting to a Capella cluster.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See above.

--

Self-Managed Couchbase Server (Javascript)::
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Javascript --> JavaScript

Expand All @@ -228,12 +228,12 @@ include::devguide:example$nodejs/self-managed-connection-crud.ts[tag=connect,ind
====


The `ClientOptions` are covered more fully on the xref:ref:client-settings.adoc[Client Settings] page.
The xref:ref:client-settings.adoc[Client Settings] page covers `ClientOptions` in detail.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Before proposing a change, it's sometimes a good idea to check that the sentence is in fact true.
Sadly, this is one of the bits of the page that definitely needs correcting.

Note that ClientOptions should be ConnectOptions -- but equally as important, the page pointed to has no useful information for the reader, and would be a disappointing journey.

Maybe consider a change like:
Connection String options are covered more fully https://docs.couchbase.com/sdk-api/couchbase-node-client/interfaces/ConnectOptions.html[in the API guide].
(or with your wording ;) )


For a deeper look at connection options, read xref:howtos:managing-connections.adoc[].
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove this line - another disappointing journey.
The
Connection String options are covered https://docs.couchbase.com/sdk-api/couchbase-node-client/interfaces/ConnectOptions.html[in the API guide].
proposed above should suffice for now.


TIP: The connection code for getting started uses the Administrator password that you were given during set up.
In any production app you should create a role restricted to the permissions needed for your app
TIP: The connection code for getting started uses the Administrator password and credentials provided during set up.
In any production app, create a role restricted to the permissions needed for your app
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removing "you should" leaves the sentence awkwardly disjointed.
Is there another way of achieving these ends?

// --
// more on this in xref:concept-docs:best-practices.adoc#roles-and-rbac[the Security documentation].

Expand Down Expand Up @@ -263,8 +263,8 @@ include::devguide:example$nodejs/capella_connection_crud.ts[tag=bucket,indent=0]

====

*Collections* allow documents to be grouped by purpose or theme, according to a specified *scope* -- see data modeling, <<data-modeling,below>>.
Here we will use the `airport` collection within the `inventory` scope from `travel-sample` bucket as an example.
*Collections* allow documents to be grouped by purpose or theme, according to a specified *scope*. For more information, see data modeling, <<data-modeling,below>>.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does one tiny clause need a new sentence?
I'm not convinced, but in any case a new sentence should be on a new line.

The example here shows the `airport` collection, within the `inventory` scope, from the `travel-sample` bucket.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whilst technically correct that all of the snippets are part of a single sample, I think most readers will see separate snippets as each being an example.

The examples here use the airport ...


[tabs]
====
Expand Down Expand Up @@ -292,11 +292,11 @@ include::devguide:example$nodejs/capella_connection_crud.ts[tag=collection,inden
== Create, Read, Update, Delete

Couchbase documents are organized into buckets, scopes, and collections.
https://en.wikipedia.org/wiki/CRUD[CRUD operations^] -- Create, Read, Update, Delete -- can be performed upon documents in a collection.
https://en.wikipedia.org/wiki/CRUD[CRUD operations^] -- Create, Read, Update, Delete actions can be performed upon documents in a collection.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CRUD expansion is a subclause - why not leave both em dashes?


=== JSON

We'll create a regular javascript object to start with:
Create a regular javascript object to start with:
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you explain the aim of this change?
If to remove the informality of "We'll" (a natural enough informality in a tutorial context, but certainly open to argument),
then "to start with" is a much greater oddity, particularly when left dangling on its own like this.

Then back up and look at what it is we're telling the reader.

May I suggest:
Create a regular JavaScript object to hold our JSON snippet:


[tabs]
====
Expand All @@ -323,12 +323,12 @@ include::devguide:example$nodejs/capella_connection_crud.ts[tag=json,indent=0]

=== Insert (Create) and Upsert

`insert` and `upsert` will both create a new document.
The difference between the two is that if a document with that key already exists, the `insert` operation will fail,
`insert` and `upsert` both create a new document.
The difference is, if a document with a key exists already, the `insert` operation fails
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

already exists sounds more natural than exists already, but it's a minor point of style, and certainly arguable.

// throwing `DocumentExistsException` --
while the `upsert` operation will succeed, replacing the content.
and the `upsert` operation replaces the content and succeeds.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The key here is it succeeds,
replacing the content is the literal side effect of that success, so that clause should follow for maximum clarity in reading the whole sentence.


We need to provide a unique ID as the key, and we'll use a UUID here:
Provide a unique ID as the key, and use a UUID here:
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you reread this sentence, and come up with an alternative suggestion?

What are the key things we're telling the developer?
They do need to use a unique ID for a key.
A UUID is one way of doing this.


.Creating a new document
[tabs]
Expand Down Expand Up @@ -356,7 +356,8 @@ include::devguide:example$nodejs/capella_connection_crud.ts[tag=upsert,indent=0]

=== Get (Read)

The `get` method reads a document from a collection. If the collection does not have a document with this ID, the `get` method also throws `DocumentNotFoundError`.
The `get` method reads a document from a collection.
The `get` method also throws `DocumentNotFoundError`, if the collection does not have a document with this ID.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm interested to know about why this is swapped around - the also now makes less stylistic sense at the beginning of the sentence.


[tabs]
====
Expand Down Expand Up @@ -407,8 +408,8 @@ include::devguide:example$nodejs/capella_connection_crud.ts[tag=replace,indent=0

====

CAUTION: When you replace a document, it's usually good practice to use xref:howtos:concurrent-document-mutations.adoc[optimistic locking].
Otherwise, changes might get lost if two people change the same document at the same time.
CAUTION: Always practice to use xref:howtos:concurrent-document-mutations.adoc[optimistic locking] when you replace a document.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We want to steer developers to best practices,
but there are use cases where even optimistic locking may not be necessary.

Else, changes might get lost if 2 people change the same document at the same time.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this an American English thing? Otherwise feels more natural here.
I don't think it's in the style guide either way.


=== Remove (Delete)

Expand Down Expand Up @@ -440,23 +441,22 @@ include::devguide:example$nodejs/capella_connection_crud.ts[tag=remove,indent=0]

== Data Modeling

Documents are organized into collections -- collections of documents that belong together.
You get to decide what it means to "belong."
Developers usually put documents of the same type in the same collection.
Documents that belong together are organized into collections.
You decide what it means to "belong."
Developers group documents of the same type in a collection.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know that the style guide gives usually as a weasel word,
but simply removing it changes the meaning in an unintended way.

Please have a think of another way we can carry the meaning.


For example, imagine you have two types of documents: customers and invoices.
You could put the customer documents in a collection called `customers`, and the invoice documents in a collection called `invoices`.
For example, there are two types of documents: customers and invoices.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

perhaps "there are" carries an implication that this applies universally - could we try:
"take" -
or would you prefer something else?

You can organize the customer documents in a collection named `customers` and the invoice documents in a collection named `invoices`.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just curious - why the change from called to named?


Each document belongs to exactly one collection.
A document's ID is unique _within_ the collection.
Every document belongs to a collection.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't this remove the precision of the sentence?

Copy link
Author

@Pallavi-Janardhan Pallavi-Janardhan Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

True may be! Should we go back to the original ?

A document's ID is unique `within` the collection.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whilst the style guide strongly dislikes italic emphasis,
we don't use monospace in this way.

Copy link
Author

@Pallavi-Janardhan Pallavi-Janardhan Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see


Different scopes can hold collections with different names.
There is no relationship between collections in different scopes.
Each collection belongs to just one scope and
a collection's name is unique within the scope.
There's no relationship between collections in different scopes.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sometimes the there is to there's change can dull the necessary emphasis that gives meaning.

Each collection belongs to 1 scope and a collection's name is unique within the scope.
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Likewise one --> 1



More details can be found on the xref:concept-docs:data-model.adoc[Data Model page].
You can find more details on the xref:concept-docs:data-model.adoc[Data Model page].
// The xref:student-record-developer-tutorial.adoc[Student Records Tutorial] gives an introduction to data modeling in a document database alongside using the {name-sdk}.


Expand Down Expand Up @@ -491,18 +491,19 @@ both

Now you're up and running, try one of the following:
Copy link
Contributor

@RichardSmedley RichardSmedley Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Everything below here is in a commented out section.
Should we be changing it - or either deleting it wholesale, or looking to use part of it?

How about uncommenting the Next Steps above here instead?
Or at least those where it makes most sense to do so.


* Our xref:hello-world:sample-application.adoc[Travel Sample Application] demonstrates all the basics you need to know;
* Explore xref:howtos:kv-operations.adoc[Key Value Operations] (CRUD) against a document database;
* Or xref:howtos:sqlpp-queries-with-sdk.adoc[Query] with our SQL-based {sqlpp} query language;
* Try longer-running queries with our xref:howtos:analytics-using-sdk.adoc[Analytics Service];
* A xref:howtos:full-text-searching-with-sdk.adoc[Full Text Search];
* Our xref:hello-world:sample-application.adoc[Travel Sample Application] demonstrates all the basics you need to know.
* Explore xref:howtos:kv-operations.adoc[Key Value Operations] (CRUD) against a document database.
* Or xref:howtos:sqlpp-queries-with-sdk.adoc[Query] with our SQL-based {sqlpp} query language.
* Try longer-running queries with our xref:howtos:analytics-using-sdk.adoc[Analytics Service].
* A xref:howtos:full-text-searching-with-sdk.adoc[Full Text Search].
* Or read up on xref:concept-docs:data-services.adoc[which service fits your use case].

=== Additional Resources

The Scala SDK includes three APIs.
The examples above show the simple blocking API, for simplicity, but you can also perform all operations in an async style using Scala `Future`, and a reactive style using Project Reactor `SMono` and `SFlux`.
Please see xref:howtos:concurrent-async-apis.adoc[Choosing an API] for more details.
The examples above show the simple blocking API.
You can also perform all the operations in an async style using Scala `Future` and a reactive style using Project Reactor `SMono` and `SFlux`.
For more information, see xref:howtos:concurrent-async-apis.adoc[Choosing an API].

The API reference is generated for each release and the latest can be found https://docs.couchbase.com/sdk-api/couchbase-scala-client/com/couchbase/client/scala/index.html[here].

Expand All @@ -515,6 +516,6 @@ The SDK source code is available on https://github.com/couchbase/couchbase-jvm-c
If you're running the SDK on your laptop against a Capella cluster, see further information on:
** Notes on xref:ref:client-settings.adoc#constrained-network-environments[Constrained Network Environments].
** xref:project-docs:compatibility.adoc#network-requirements[Network Requirements].
** If you have a consumer-grade router which has problems with DNS-SRV records review our xref:howtos:troubleshooting-cloud-connections.adoc#troubleshooting-host-not-found[Troubleshooting Guide].
* Our https://forums.couchbase.com/c/scala-sdk/37[community forum] is a great source of help.
** If you have a consumer-grade router that has problems with DNS-SRV records, review xref:howtos:troubleshooting-cloud-connections.adoc#troubleshooting-host-not-found[Troubleshooting Guide].
* The https://forums.couchbase.com/c/scala-sdk/37[community forum] is a great source of help.
////