Skip to content

Add examples for connecting, queriying, logging and installing #1

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

Merged
merged 6 commits into from
Oct 7, 2025
Merged

Add examples for connecting, queriying, logging and installing #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d9e5494
Add examples for connecting, queriying, logging and installing
emilienbev Oct 3, 2025
6bdd552
Delete third party integrations, rename various Java/JVM to C#/.NET
emilienbev Oct 3, 2025
9fdc217
Remove other mentions of Java, add ConnectionString and options code …
emilienbev Oct 7, 2025
40270d3
Remove explicit mention of milliseconds in managing-connections cstri…
emilienbev Oct 7, 2025
ce19193
Clarify With[...]Parameters warning
emilienbev Oct 7, 2025
a00905c
Specify the plural
emilienbev Oct 7, 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
2 changes: 1 addition & 1 deletion modules/hello-world/pages/overview.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

= .NET Analytics SDK

The .NET Analytics SDK allows you to connect to an Enterprise Analytics cluster from Java.
The .NET Analytics SDK allows you to connect to an Enterprise Analytics cluster using C#.
For connecting to a Couchbase Server Cluster -- self-managed, or Capella Operational --
see our xref:dotnet-sdk:hello-world:overview.adoc[.NET Operational SDK].

Expand Down
95 changes: 32 additions & 63 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 @@ -20,87 +20,56 @@ Install and configure an xref:enterprise-analytics:intro:intro.adoc[Enterprise A
// After creating the cluster, add your IP address to the list of allowed IP addresses.
// TODO: Link to https://docs.couchbase.com/columnar/admin/ip-allowed-list.html

[#minimum-java-version]
=== Minimum Java Version
[#minimum-dotnet-version]
=== Minimum .NET Version

The {name-sdk} requires Java 8 or later.
We recommend using the most recent long-term support (LTS) version of OpenJDK.
The {name-sdk} requires .NET 8 or later.
We recommend using the most recent long-term support (LTS) version of .NET.

TIP: Remember to keep your Java installation up to date with the latest patches.
== Adding the SDK to an Existing Project

[maven-project-template]
== Maven Project Template
Add the NuGet package to your `*.csproj` file, or add it using the command line:

The SDK's source code repository includes an
https://github.com/couchbaselabs/couchbase-analytics-jvm-clients/tree/main/couchbase-analytics-java-client/examples/maven-project-template[example Maven project]
you can copy to get started quickly.
[source,shell]
----
dotnet add package Couchbase.AnalyticsClient
----

== Adding the SDK to an Existing Project
[source,xml]
----
<PackageReference Include="Couchbase.AnalyticsClient" Version="1.0.0" />
----

Declare a dependency on the SDK using its xref:project-docs:sdk-full-installation.adoc[].

To see log messages from the SDK, xref:howtos:logging.adoc[include an SLF4J binding in your project].

[quickstart]
== Connecting and Executing a Query

[source,java]
[source,csharp]
----
import com.couchbase.analytics.client.java.Cluster;
import com.couchbase.analytics.client.java.Credential;
import com.couchbase.analytics.client.java.QueryResult;

import java.util.List;

public class Example {
public static void main(String[] args) {
var connectionString = "https://<your_hostname>:" + PORT;
var username = "...";
var password = "...";

try (Cluster cluster = Cluster.newInstance(
connectionString,
Credential.of(username, password),
// The third parameter is optional.
// This example sets the default query timeout to 2 minutes.
clusterOptions -> clusterOptions
.timeout(it -> it.queryTimeout(Duration.ofMinutes(2)))
)) {

// Execute a query and buffer all result rows in client memory.
QueryResult result = cluster.executeQuery("select 1");
result.rows().forEach(row -> System.out.println("Got row: " + row));

// Execute a query and process rows as they arrive from server.
cluster.executeStreamingQuery(
"select 1",
row -> System.out.println("Got row: " + row)
);

// Execute a streaming query with positional arguments.
cluster.executeStreamingQuery(
"select ?=1",
row -> System.out.println("Got row: " + row),
options -> options
.parameters(List.of(1))
);

// Execute a streaming query with named arguments.
cluster.executeStreamingQuery(
"select $foo=1",
row -> System.out.println("Got row: " + row),
options -> options
.parameters(Map.of("foo", 1))
);
}
}
using Couchbase.AnalyticsClient;
using Couchbase.AnalyticsClient.HTTP;
using Couchbase.AnalyticsClient.Options;

var credential = Credential.Create("username", "password");

var cluster = Cluster.Create(
connectionString: "https://analytics.my-couchbase.example.com:18095",
credential: credential)
);

var result = await cluster.ExecuteQueryAsync("SELECT i from ARRAY_RANGE(1, 100) AS i;").ConfigureAwait(false);

await foreach (var row in result.ConfigureAwait(false))
{
Console.WriteLine(row.ContentAs<JsonElement>());
}
----


=== Connection String

The `connStr` in the above example should take the form of "https://<your_hostname>:" + PORT
The `connectionString` in the above example should take the form of "https://<your_hostname>:" + PORT

include::{version-common}@analytics-sdk:shared:partial$connstr.adoc[tag=connstr]

Expand Down
204 changes: 35 additions & 169 deletions modules/howtos/pages/logging.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
= Logging
:page-toclevels: 2
:description: Configuring logging with the Columnar Java SDK.
:description: Configuring logging with the .NET Analytics SDK.

[abstract]
{description}
Expand All @@ -10,186 +10,52 @@ The {name-sdk} emits log messages that can help with troubleshooting.

== Logging

The {name-sdk} uses https://www.slf4j.org[SLF4J], a logging façade that lets you use any logging framework that has an SLF4J binding.
This includes popular Java logging frameworks like Log4j, Logback, and `java.util.logging` (JUL).
An `ILoggerFactory` can be provided to the `ClusterOptions` when creating a `Cluster`.

To see log messages from the Couchbase SDK, add an SLF4J binding as a dependency of your project.

[slf4j-api-versions]
.SLF4J API versions
[example-usage]
.Using Serilog
[NOTE]
====
At the time of writing, there are two different versions of the SLF4J API:

*Version 2* is the modern version of SLF4J.
It is actively maintained, and recommended for most users.

*Version 1.7* is no longer maintained, but you can still use it if your preferred SLF4J binding does not support version 2.

The Couchbase SDK is compatible with both versions of the SLF4J API.
The SDK's Maven POM has a dependency on version 1.7, but you can override this by using version 2 in your project.
====

[log4j2]
=== Using Log4j 2

Log4j 2 is a popular and flexible logging framework.
This section shows how to configure your project to use Log4j 2 with the Couchbase SDK.

First, add an https://logging.apache.org/log4j/2.x/log4j-slf4j-impl.html[SLF4J binding for Log4j 2] as a dependency of your project.
The following example uses the binding for SLF4J API version 2.

[{tabs}]
====
Maven::
+
--
Add these as children of the `dependencies` element.

.`*pom.xml*`
[source,xml]
----
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-slf4j2-impl</artifactId>
<version>2.22.0</version>
</dependency>

<!-- If your SLF4J binding requires API version 2
(like log4j-slf4j2-impl in this example!),
add this dependency to your project to ensure
Maven uses the correct SLF4J API version. -->
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>2.0.9</version>
</dependency>
----

TIP: An alternate way to ensure Maven uses the correct version of the SLF4J API is to declare the dependency on `log4j-slf4j2-impl` *before* the dependency on the Couchbase SDK.
See the Maven documentation on https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Transitive_Dependencies[Transitive Dependencies] to learn more about how Maven resolves transitive dependency version conflicts.
--
Gradle::
+
--
.`*build.gradle*`
[source,groovy]
----
// Add this to the `dependencies` section:
implementation("org.apache.logging.log4j:log4j-slf4j2-impl:2.22.0")
----
NOTE: Gradle automatically uses the correct SLF4J API 2.x dependency required by `log4j-slf4j2-impl`, even though the Couchbase SDK declares a dependency on SLF4J API 1.7.
--
====

[configuring-log4j]
==== Configuring Log4j 2 output

Log4j 2 needs a configuration file to tell it which messages to log, where to write them, and how each message should be formatted.

Here's an example `log4j2.xml` configuration file you can use to get started.
It tells Log4j 2 to log messages to the console, and sets some reasonable logging levels.
Using `Serilog` and wiring it to the SDK's `Microsoft.Extensions.Logging` API:

TIP: If your project uses the https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html[Maven Standard Directory Layout], this file should live in the `src/main/resources` directory.
This makes it available at runtime as a class path resource.

.src/main/resources/log4j2.xml
[source,xml]
[source,csharp]
----
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
<Appenders>
<Console name="Console" target="SYSTEM_OUT">
<PatternLayout pattern="%d{ISO8601_OFFSET_DATE_TIME_HHCMM} %-5p [%c:%L] %m%n"/>
</Console>
</Appenders>
<Loggers>
<!-- Trace/debug/info messages from the Couchbase SDK's repackaged Netty
are of little interest, unless you're debugging a network issue. -->
<Logger name="com.couchbase.client.core.deps.io.netty" level="warn"/>
Log.Logger = new LoggerConfiguration()
.MinimumLevel.Is(LogEventLevel.Debug)
.Enrich.FromLogContext()
.WriteTo.Console()
.WriteTo.File(
path: "Logs/my-logs.log",
rollingInterval: RollingInterval.Day,
shared: true)
.CreateLogger();

<!-- Most messages from the Couchbase SDK are logged under
this prefix. Change the level to "debug" to see more
details about SDK activity, or "warn" to see less.
In production environments, we recommend "info". -->
<Logger name="com.couchbase" level="info"/>
var loggerFactory = LoggerFactory.Create(builder =>
{
builder.ClearProviders();
builder.AddSerilog();
});

<!-- The default level for everything else. -->
<Root level="info">
<AppenderRef ref="Console"/>
</Root>
</Loggers>
</Configuration>
----
var clusterOptions = new ClusterOptions().WithLogging(loggerFactory);

Consult the https://logging.apache.org/log4j/2.x/manual/configuration.html[Log4J 2 configuration documentation^] for more information and advanced configuration options.

[jul]
=== Using `java.util.logging` (JUL)

If `java.util.logging` (JUL) is your preferred logging framework, add the `slf4j-jdk14` SLF4J binding as dependency of your project.

[{tabs}]
====
Maven::
+
--
Add these as children of the `dependencies` element.
var credential = Credential.Create("username", "password");

.`*pom.xml*`
[source,xml]
var cluster = Cluster.Create(
connectionString: "https://analytics.my-couchbase.example.com:18095",
credential: credential,
clusterOptions: clusterOptions
);
----
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-jdk14</artifactId>
<version>2.0.9</version>
</dependency>

<!-- If your SLF4J binding requires API version 2
(like slf4j-jdk14 in this example!),
add this dependency to your project to ensure
Maven uses the correct SLF4J API version. -->
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>2.0.9</version>
</dependency>
----

TIP: An alternate way to ensure Maven uses the correct version of the SLF4J API is to declare the dependency on `slf4j-jdk14` *before* the dependency on the Couchbase SDK.
See the Maven documentation on https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Transitive_Dependencies[Transitive Dependencies] to learn more about how Maven resolves transitive dependency version conflicts.
--
Gradle::
+
--
.`*build.gradle*`
[source,groovy]
----
// Add this to your `dependencies` section:
implementation("org.slf4j:slf4j-jdk14:2.0.9")
----
NOTE: Gradle automatically uses the correct SLF4J API 2.x dependency required by `slf4j-jdk14`, even though the Couchbase SDK declares a dependency on SLF4J API 1.7.
--
====

[configuring-the-jdk-logger]
==== Configuring a JUL Logger

By default, JUL logs INFO level and above.
If you want to set it to DEBUG (or the JUL equivalent: FINE) you can do it like this programmatically:

[source,java]
.Using minimal logging without 3rd party sinks
[source,csharp]
----
// Make sure to do this as soon as your application starts,
// and before calling `Cluster.newInstance()`.
Logger logger = Logger.getLogger("com.couchbase.client");
logger.setLevel(Level.FINE);
for (Handler h : logger.getParent().getHandlers()) {
if (h instanceof ConsoleHandler) {
h.setLevel(Level.FINE);
}
}
var loggerFactory = LoggerFactory.Create(builder =>
{
builder.ClearProviders();
builder.SetMinimumLevel(LogLevel.Debug);
builder.AddConsole();
});
----

TIP: We do not recommend using JUL in production.
Dedicated logging frameworks like Log4j 2 and Logback are more configurable, and tend to perform better than JUL.
Loading