Connect SPSync to Azure AI Search

SPSync writes one Azure AI Search index per table: a list’s main table, each multi-value child table and the shared users table. Documents are merged by key, and a row deleted in SharePoint is removed from the index. With an embedding provider configured, each index also gets a vector field, so keyword, vector and hybrid queries all work against the same index.

Before you start

• An Azure AI Search service. The Basic tier or above suits a real list; the no-cost level has small index and document limits.
• Owner or Contributor on the service (to read its keys), or someone who can give you the admin 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

There is no database to create: SPSync creates the indexes. There is also no narrower credential to give it today. Index creation needs an admin key, and a query key is refused. In the Azure portal, open the service, then Settings, Keys, and copy the primary or secondary admin key. Use the secondary for SPSync so you can rotate the primary without a gap.

The service must accept keys. Under Settings, Keys, API access control, choose API keys or Both. If the service is set to role-based access control only, key requests are refused.

An admin key can change or delete any index on the service. If the service also serves your own search application, create a second service for SPSync’s indexes, or keep the key out of anything else’s reach.

Allow SPSync to reach it

The service endpoint is https://<service>.search.windows.net on port 443. On the desktop app and a self-hosted server the connection starts from that machine. For the Azure managed application, it starts from the address the application connects out from.

• Public endpoint with a firewall: under Settings, Networking, choose Selected IP addresses and add the address. Add the portal’s own address range too if you want to keep browsing the indexes there.
• Private endpoint: choose Private under Networking, create the private endpoint and run SPSync inside the virtual network, or peered to it.
• No firewall: the default is open to the internet, protected by the key alone.

Encrypt the connection

The endpoint is https only and uses a certificate from a public authority, so there is nothing to switch on. Enter the URL with https://.

Authentication SPSync supports today

The admin API key only. Microsoft Entra ID and managed identity sign-in to the search service are not supported yet. If you add an embedding provider, that has its own key (see below).

Connect from SPSync

• Desktop app: open the Destination screen, choose Azure AI Search, enter the endpoint and the admin API key, then choose Test connection. SPSync manages the local state file itself.

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

  export SPSYNC_AAIS_STATE_PATH=/var/lib/spsync/aais-state.duckdb
  export SPSYNC_AAIS_ADMIN_KEY='<admin 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 azure-ai-search --connection-string-env SPSYNC_AAIS_STATE_PATH \
    --dataset-name main \
    --azure-ai-search-endpoint https://my-service.search.windows.net \
    --azure-ai-search-api-key-env SPSYNC_AAIS_ADMIN_KEY \
    --client-id <entra-app-client-id>

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

Index names

Azure AI Search allows only lowercase letters, digits and dashes in an index name, so every underscore in a table name becomes a dash. With the prefix dev, a list called Tasks is the index dev-tasks, and its multi-value column Tags is dev-tasks--tags. The users table is sp-users. If a column changes type, SPSync adds a new index ending -v2 rather than failing, because Azure AI Search cannot change a field’s type in place.

Every index also has an sp_key text field, which is the document key. The service requires a text key, and SharePoint ids are numbers.

Embeddings and the vector field

Set an embedding provider to give each index a vector field, sp_embedding by default, with a companion sp_embedding_hash. SPSync embeds the text of the columns you name, joined in order, and re-embeds only the rows whose text changed. Changing the model re-embeds every row.

Setting	What it is
Provider	openai, azure-openai, or local (an offline model, no key needed).
Model	The model name. For azure-openai, the deployment name.
Dimensions	The vector width. It must match the model. Changing it later starts a new index ending -v2.
Columns	The destination column names to embed, for example title and description.
Embedding API key	The OpenAI or Azure OpenAI key. Not the search admin key.
Azure OpenAI endpoint	Needed for azure-openai only.

On the desktop app these are the Embedding fields on the same form. On the CLI they are the --azure-ai-search-embedding-* flags, with the key and endpoint passed as environment variable names. The local provider downloads its model on first use, so the machine needs outbound internet access then. SPSync fills the index and leaves querying to the service: it configures one default HNSW vector profile and no semantic ranking or scoring profiles.

What Test connection and doctor check

Both list the service’s index names with the key. A pass means the endpoint is reachable and the key is accepted as an admin key. It does not check the embedding provider’s key, and it does not create anything. spsync doctor reports the probe as destination-connectivity.

Common errors

What you see	What it means and the fix
Timeout or connection refused	The service firewall or a private endpoint is blocking SPSync, or the endpoint is wrong.
HTTP 403 listing indexes	The key is wrong or revoked, or it is a query key. Use an admin key.
HTTP 403 with API keys disabled	The service is set to role-based access only. Set API access control to Both.
HTTP 400 naming an index or field	A name breaks the service’s rules. Index names are lowercase with dashes; SPSync converts them, so check for a hand-made index with the same name.
HTTP 400 about vector dimensions	The model’s dimensions differ from the field. Set the dimensions to the model’s output size, or let SPSync create the -v2 index.
HTTP 429 or 503	The service is throttling. Scale the replicas or partitions, or wait. SPSync resends on the next round.