Cb analytics links

Managing Analytics links

A link in Analytics connects external storage so it can be queried as a dataset. The 5 tools cover the lifecycle: list, get, create, update, delete.

Link types and their config

S3

{
  "type": "s3",
  "region": "us-east-1",
  "accessKeyId": "AKIA...",
  "secretAccessKey": "...",
  "serviceEndpoint": "https://s3.example.com",   // optional (MinIO, etc.)
  "sessionToken": "..."                          // optional (STS)
}

Azure Blob

{
  "type": "azureblob",
  "accountName": "myacct",
  "accountKey": "...",                  // OR sharedAccessSignature
  "sharedAccessSignature": "?sv=...",
  "endpoint": "https://blob.example.com"   // optional
}

GCS

{
  "type": "gcs",
  "jsonCredentials": "{...full service account JSON...}",
  // OR
  "applicationDefaultCredentials": true,
  "endpoint": "https://storage.googleapis.com"  // optional
}

Remote Couchbase

{
  "type": "couchbase",
  "hostname": "remote.example.com",
  "username": "analytics",
  "password": "...",
  "encryption": "full",            // none | half | full
  "certificate": "-----BEGIN ...",
  "clientCertificate": "...",      // optional mTLS
  "clientKey": "..."
}

Credentials in audit logs

All of the above keys (accessKeyId, secretAccessKey, accountKey, jsonCredentials, password, clientKey, etc.) are auto-redacted in the audit log. You can be confident that passing credentials through create_link won't leave them in the audit trail.

Workflow

1. list_links(dataverse="X") — see what already exists; don't recreate.
2. create_link(name, dataverse, config) — create new.
3. get_link(name) — verify the type and active datasets.
4. update_link(name, config) — rotate credentials without recreating the datasets that point to it.
5. delete_link(name) — safe only when no datasets reference it; otherwise it returns a RequestError.

Naming convention

The community convention is <source>-<purpose>, e.g. s3-events, azure-archive, cb-replica. Stick to it for consistency.

What to avoid

• Don't put credentials in source control. Always upsert them via the tool at deploy time, or read from a secrets manager.
• Don't switch a link's type via update; delete and recreate instead.
• Don't rotate credentials by deleting + recreating — use update_link so existing datasets stay attached.

Rate limits & safety

Link tools split across categories:

• read (60/sec): list_links, get_link.
• write (1/sec, intentional): create_link, update_link, delete_link.

Link mutations are destructive — deleting a link with attached datasets breaks downstream queries; updating credentials wrong takes ingestion offline. The 1/sec write limit is deliberately constraining. If you're batch-creating links from a config file, sequence the calls and accept the throttling.

If RateLimitExceeded comes back from a create_link / update_link / delete_link, honour retry_after_sec. Don't retry-storm — sleep for the indicated duration, then continue.

list_links and get_link share the global read bucket with every other read-only tool on the server. In a "show me everything about the link landscape" workflow, prefer one list_links plus targeted get_link calls over polling.

Related skills

• cb-analytics-schema — once a link is connected and datasets exist, use this to discover their field shapes
• cb-analytics-query — querying data that arrives via links
• cb-analytics-mcp-setup — configuring the MCP server credentials (S3/Azure/GCS keys go in env vars, not inline)