SKILL.md

name	server-querying-nodejs
summary	Write and execute SQL++ (N1QL) queries from Node.js against Couchbase — SELECT, DML, parameterization, scan consistency, prepared statements, and query_context
description	Write and execute SQL++ (N1QL) queries from Node.js against Couchbase — SELECT, DML, parameterization, scan consistency, prepared statements, and query_context
compatibility	Node.js SDK 4.x. Requires couchbase>=4.0.
metadata	last_verified min_server_version handoff 2026-05 7.0 condition skill user asks about connection setup or SDK configuration server-connection-nodejs condition skill user asks about slow queries or index recommendations server-query-optimizer condition skill user asks about CAS, bulk ops, sub-document, or SDK patterns sdk-patterns-nodejs condition skill user asks about full-text search or vector search search-nodejs condition skill user asks about transactions or atomic multi-document operations transactions-nodejs condition skill user asks about OLAP queries or the Analytics service analytics-nodejs condition skill user is on Server 8.x and asks about columnar or OLAP queries columnar-analytics

SQL++ Querying — Node.js

Basic Query

const result = await cluster.query(
    'SELECT META().id, o.status, o.total FROM `myapp`._default.orders o WHERE o.status = $status LIMIT 10',
    { parameters: { status: 'pending' } }
);
for (const row of result.rows) console.log(row);

Scan Consistency

const { QueryScanConsistency, MutationState } = require('couchbase');

// Read your own writes
const upsertResult = await collection.upsert('order_1', doc);
const result = await cluster.query(
    "SELECT * FROM `myapp`._default.orders WHERE META().id = 'order_1'",
    { consistentWith: MutationState.from(upsertResult) }
);

// Strict read-after-write
const result2 = await cluster.query('SELECT ...',
    { scanConsistency: QueryScanConsistency.RequestPlus });

Prepared Statements

const result = await cluster.query(
    'SELECT * FROM `myapp`._default.orders WHERE customerId = $cid',
    { parameters: { cid: 'c500' }, adhoc: false }
);

query_context

const result = await cluster.query(
    "SELECT * FROM orders WHERE status = 'pending'",
    { queryContext: 'default:myapp._default' }
);

DML

Boundary note: This section covers SDK execution of DML statements. For SQL++ DML syntax (INSERT, UPDATE, DELETE, UPSERT, MERGE), see sqlpp-language.

await cluster.query(
    'UPDATE `myapp`._default.orders SET status = $s WHERE META().id = $id',
    { parameters: { s: 'shipped', id: 'order::1' } }
);

Scope-Level Query

When working within a named scope, use scope.query() to omit the bucket/scope prefix from every statement:

const scope = cluster.bucket('myapp').scope('inventory');

const result = await scope.query(
    'SELECT * FROM orders WHERE status = $s',
    { parameters: { s: 'pending' } }
);
result.rows.forEach(row => console.log(row));

See ../../shared/server/sql-syntax.md for SELECT syntax, JOINs, MERGE, window functions, and built-in functions.