Couchbase

Overview

Signals reads customer and event documents straight from a Couchbase cluster on a schedule and sends the columns you nominate to your ad platforms.

Reading it directly means there is no file job to maintain and nothing to go stale between runs. Signals reads only; nothing is written back.

Couchbase organizes documents into buckets, scopes and collections rather than tables. Where this page says table name, enter the collection holding your records.

You can point it at a collection, or at a query. The query path is what you want when the shape Signals needs does not match anything you already have.

Scopes and collections arrived in Couchbase Server 7.0, and every bucket is created with a scope called _default holding a collection called _default, which is also where an upgrade from a release before 7.0 leaves all the data that was already there. A name such as customers is consequently half an address. SQL++ completes a bare collection name from the query context, which supplies the bucket and the scope, and with no context set the statement has to spell the path out as bucket.scope.customers. Two scopes in one bucket can each hold a customers collection, and reading the wrong one produces rows rather than an error.

Supported destinations

Destinations supported by Couchbase

Category	Supported
Offline Conversions	Google Offline Conversions API Google Store Sales LinkedIn Offline Conversions API Meta Offline Conversions API OpenAI Offline Conversions API Snapchat Offline Conversions API TikTok Offline Events API
Lead Conversions	Google Enhanced Conversions for Leads LinkedIn Leads Conversions API Meta Conversions API for CRM Snapchat Leads Conversions API TikTok CRM Integrations
Custom Audience	Google Customer Match Meta Custom Audience Snapchat Custom Audience TikTok Custom Audience

Authentication

In Studio, open Sources, find the Database category, and click the Couchbase tile.

Field	What it is	Where to find it
Authentication Name	Your own label for this set of credentials.	You choose it. Name it for the database it belongs to.
Username	The database user Signals connects as.	Created in the database by your administrator.
Password	The password for that user.	Set when the user was created.

Couchbase exposes several ports for different services, and a managed deployment may differ again. Check the port against what your cluster publishes for client connections.

Caution

Create a dedicated read-only user for Datahash rather than reusing an application or administrator account. It keeps the connection working when someone rotates a password, and it stops the connection seeing more than it needs. Enter the password on the Datahash connection screen only.

Reading a document and querying for it are separate permissions here, held by separate roles. Data Reader, data_reader, covers retrieval by key, and the Couchbase documentation states plainly that it does not grant the ability to run SQL++ queries. Query Select, query_select, is the role that permits a SELECT statement over the data it is granted on. An account carrying Data Reader on its own therefore signs in, holds a real role against the bucket, and has every query it sends refused, which sends whoever is diagnosing it back around the bucket permissions instead of to the query role that was never granted. Where the connection reads through a query, Query Select on the collections that query touches is the grant to check for.

Both roles carry the level they were granted at inside the role itself. query_select[appdata] covers every collection in that bucket, query_select[appdata:crm] covers every collection in that scope, query_select[appdata:crm:customers] covers that one collection, and query_select[*] covers every bucket on the cluster. Where the grant names a collection, a collection created afterwards falls outside it and fails its first read on authorization rather than coming back empty. Where it names the bucket or the scope, later collections are covered already and re-granting the role changes nothing.

A local user is defined on the cluster itself, while an external user’s credentials live in an LDAP directory the cluster consults. Establish which of the two this account is before anyone needs to rotate the password, because the two are rotated in different places.

Configuration

Instance Setup

Select the Integration Type, which is the kind of data your records hold. Offline Events is the common choice. Give the instance a name, then choose the table path or the query path. On either path you enter the Database Name, which Couchbase calls the bucket, the Host Name, the Query Service Port and the Scope, and then either the Collection Name or a query.

The integration type decides the columns Signals expects and which destinations the connection can feed, so it is worth settling before anyone models the data. It also decides which file format you get on the next screen.

Which number the Query Service Port field wants

Each Couchbase service answers on a number of its own, and this field asks for the Query service. 8093 is where the Query service accepts SQL++ over HTTP. 11210 belongs to the Data service, which is what key-value retrieval goes through. 8091 is cluster administration and the Couchbase Web Console. Entering it here aims the connection at the administration interface instead of at the query engine.

Each of the three has an encrypted counterpart on a number of its own: 18093 for the Query service, 11207 for the Data service, 18091 for administration. On a cluster configured to accept only encrypted client traffic the three plain numbers do not answer at all.

Table path

Enter the connection details including the collection name, then complete the setup. The name is typed rather than picked from a list, so it has to match the database exactly.

Query path

Enter the connection details without the collection name, then write the query. Preview the results before finishing, and read the column names in the output rather than just the row count: a query that runs but returns the wrong names will fail silently once the connection is live.

Manage instance

One instance reads one table or query for one integration type. To read another, add another instance from the Manage existing instance table. To change an existing one, open it from there, click the edit option in the menu to the top right, update the fields and click Finish.

File format and schema

Download the file format from the setup screen and shape the collection to it. The column names are what Signals matches on, so a column that has been renamed or cased differently is not recognized and the row it belongs to is dropped rather than reported.

On the query path the same rule applies to the column aliases your query returns. Aliasing to the expected names is the usual way to reconcile data you cannot or should not restructure.

Data & identifiers

Personal identifiers are normalized and hashed before they are sent to a destination.

Best practices

• Use a dedicated read-only user scoped to the data Datahash reads, rather than an application account.
• Prefer the query path with explicit column aliases over pointing at a raw collection. It lets your team change the underlying model without breaking the connection.
• Enter a Host Name that runs the Query service, and do not plan the read around bucket replicas. A replica vBucket is there so the cluster survives losing the node holding the active copy, and an ordinary read is served by the active copy whichever node the client contacts; the SDK does expose explicit replica reads, getAnyReplica among them, but those exist for the moments the active copy is unavailable rather than as a way to spread scheduled load. Multi-Dimensional Scaling is what moves the work, and it moves as much of it as the index covers. Where Query and Index run on nodes of their own, planning and index scanning happen there, while a projection reaching past the index still fetches the documents from the Data service nodes your application depends on.
• Give the user read access to the one bucket rather than cluster-wide permissions.
• Project nested document fields into top-level values with the expected names.
• Clean the data in the view or query: lowercase email, phone in E.164, no stray whitespace. Hashing a badly formatted value produces a hash that will never match.
• Rotate the password periodically and update the connection afterwards.

Troubleshooting & FAQ

The connection times out rather than reporting bad credentials. That points at reachability rather than authentication. Confirm the host is exposed, the port is open, and any firewall or allow list permits the connection.

Credentials are rejected. Check the user can read the data from a client of its own first. Most failures here are permissions rather than typos.

The collection name is rejected. It is typed rather than selected, so it has to match exactly.

The query previews correctly but nothing is delivered. The column names it returns do not match the expected schema. Alias them to the names in the downloaded file format.

The collection is not found. Couchbase nests collections inside scopes inside buckets. Confirm you are naming the collection and not the bucket.

A query against a new collection answers with a complaint about an index instead of rows. SQL++ is planned against whatever indexes exist, and where none of them can serve the statement the Query service declines to run it: No index available on keyspace ... that matches your query. Use CREATE PRIMARY INDEX ON ... to create a primary index, or check that your expected index is online. A collection created and never indexed meets this on its first read, and so does a collection whose index has not finished building, which is the second half of that sentence and the half that gets read past. That refusal is the behavior on releases before Couchbase Server 7.6. Index the fields the query filters on.

The rows are right and the read takes far longer than the size of the collection accounts for. Sequential scans are switched on globally by default from Couchbase Server 7.6, so a statement no index can serve completes by walking keys through the Data service rather than being refused. Nothing is raised while it runs, which is what leaves an unindexed read in place for months. EXPLAIN on the statement names #sequentialscan where it would otherwise name an index, and that is the confirmation to look for. Creating an index over the filtered fields moves the plan back onto it.

It was working and stopped. The password may have been changed or the user disabled. A dedicated service user avoids this.