Connect SPSync to Qdrant

SPSync writes one Qdrant collection per table: a list’s main table, each multi-value child table and the shared users table. Each row becomes a point whose payload is the row, keyed by an id SPSync derives from the row’s key. A row deleted in SharePoint is deleted from the collection. SPSync does not write a vector today, so the collections hold payload only and are useful for filtering and lookup alongside vectors you load another way.

Before you start

• A Qdrant cluster you can reach, and its URL, for example https://xyz.cloud.qdrant.io:6333 or http://qdrant.internal:6333.
• Access to the cluster’s configuration (self-hosted) or the Qdrant Cloud console, to create an API key.
• Nothing to install on the machine that runs SPSync. SPSync keeps a small local state file (a DuckDB file) that records what it last sent, so it sends only the rows that changed. Keep that file on a disk that survives restarts.

Create the database and a least-privilege user

Qdrant has no users. Access is by API key.

• Qdrant Cloud: in the console, open the cluster, then API Keys, create a key and give it read and write access. Use a key limited to the collections SPSync will create if your plan offers collection-level access. A read-only key cannot create or write.
• Self-hosted: set service.api_key in the configuration (or the QDRANT__SERVICE__API_KEY environment variable) and use that value. A read-only key (service.read_only_api_key) is not enough. This is from the Qdrant documentation and has not been run here against a test cluster.

A cluster with no key set accepts any caller, which suits a closed test network only. SPSync accepts that: leave the key blank.

SPSync creates the collections itself, named from the --prefix and the list, for example dev_projects. When a column changes type, Qdrant would silently overwrite an existing payload index, so SPSync checks first and starts a new collection ending _v2.

Allow SPSync to reach it

Qdrant’s REST API is on TCP 6333, and 443 behind a load balancer or on some cloud plans. The connection starts from the machine that runs SPSync. For the Azure managed application, allow the address it connects out from.

• Self-hosted: allow the SPSync address in the host firewall or security group for 6333. Do not expose 6333 to the internet without a key and TLS.
• Qdrant Cloud: under the cluster’s Configuration, add the address to the IP allow-list, or use private networking and run SPSync inside it.

Encrypt the connection

Use an https:// URL. SPSync uses the standard Qdrant client with the URL as given, and it has no setting for a private certificate authority, so the certificate must chain to a root the machine already trusts. Qdrant Cloud’s does. A self-hosted node answers plain http:// unless you turn on TLS in its configuration, or put it behind a proxy that does. An http:// URL sends the key in clear text.

Authentication SPSync supports today

An API key, or none for a cluster that has no key. There is no basic authentication, and token-based role access (JWT) is not supported.

Connect from SPSync

• Desktop app: open the Destination screen, choose Qdrant, enter the Qdrant URL and, if the cluster has one, the Qdrant API key, then choose Test connection. SPSync manages the local state file itself.

• CLI: the config names environment variables, never the key itself. SPSYNC_QDRANT_STATE_PATH holds the path of the local state file, not a network address.

  export SPSYNC_QDRANT_STATE_PATH=/var/lib/spsync/qdrant-state.duckdb
  export SPSYNC_QDRANT_API_KEY='<api key>'
  spsync export-config --output replication.yaml \
    --site-url https://contoso.sharepoint.com/sites/x --list Projects \
    --pipeline-name spsync_dev --prefix dev \
    --destination-kind qdrant --connection-string-env SPSYNC_QDRANT_STATE_PATH \
    --dataset-name main \
    --qdrant-url https://xyz.cloud.qdrant.io:6333 \
    --qdrant-api-key-env SPSYNC_QDRANT_API_KEY \
    --client-id <entra-app-client-id>

  For a cluster with no key, leave out the last key flag.

• AI assistant: with the admin MCP server connected, ask for the destination requirements, then let the assistant create the destination with the URL. You enter the API key on the secure entry page, never in the chat.

What Test connection and doctor check

Both list the cluster’s collections. A pass means the URL is reachable, the certificate is trusted and the key is accepted for reading. It does not prove the key can create a collection or write points, so a read-only key passes the test and fails at the first sync. spsync doctor reports the probe as destination-connectivity.

Common errors

What you see	What it means and the fix
Connection refused, timeout or ConnectError	A firewall, security group or IP allow-list is blocking the port, or the URL or port is wrong.
SSL: CERTIFICATE_VERIFY_FAILED	The certificate is self-signed or from a private CA. Use a public certificate, or trust your CA on the machine that runs SPSync.
Unexpected Response: 401 or 403 (Forbidden)	The key is wrong, or it is read-only. Use a key with write access.
Unexpected Response: 404 on a Qdrant Cloud URL	The path or port is wrong. Use the cluster URL the console shows, ending in the port.
A first sync fails after the test passed	The key can list but not write. Replace it with a read and write key.