Provider Configuration

Configure AI providers for embedding generation and completion. Use SHOW AI PROVIDERS to see all available providers and their current status.

API Key

ai.set_api_key()

Sets the API key for an AI provider. Optionally activates it as the current provider.

Syntax	`ai.set_api_key(<provider>, <apiKey> [, <activate>])`
Arguments	Name	Type	Description
	`<provider>`	`STRING`	Provider name (see Supported Providers)
	`<apiKey>`	`STRING`	The API key
	`<activate>`	`BOOL`	Optional. Whether to set this as the active provider (default: `true`)
Return Type	`BOOL`

By default, calling ai.set_api_key() both sets the key and activates the provider:

GQL
RETURN ai.set_api_key("openai", "sk-...")

Each provider stores one API key. Calling ai.set_api_key() again for the same provider overwrites the previous key. To set keys for multiple providers without activating them, pass false as the third argument, then use ai.set_provider() to switch:

GQL
RETURN ai.set_api_key("gemini", "AQ.za...", false)

Custom Endpoint

ai.set_base_url()

Points an OpenAI-compatible provider (one that mirrors OpenAI's API format, so it can be reached by swapping the base URL) at a custom endpoint, such as a local LM Studio on a non-default host or port, a self-hosted gateway, or a proxy, without setting a *_BASE_URL environment variable.

Syntax	`ai.set_base_url(<provider>, <url>)`
Arguments	Name	Type	Description
	`<provider>`	`STRING`	Provider name (see Supported Providers). An unknown provider raises an error.
	`<url>`	`STRING`	The OpenAI-compatible base URL, for example `http://localhost:1234/v1`. The URL is not validated, so make sure it points at a reachable endpoint.
Return Type	`BOOL`

The base URL is stored with the provider, so it survives a restart. If the provider is the active embedding and/or completion provider, the change takes effect immediately; a non-active provider has its configuration updated and applies the URL the next time it is activated.

GQL
-- Point the local LM Studio provider at a server on another host
RETURN ai.set_base_url("lmstudio", "http://192.168.1.50:1234/v1")

-- Route the openai provider through a self-hosted gateway or proxy
RETURN ai.set_base_url("openai", "http://localhost:8080/v1")

Azure OpenAI

The openai provider can target an Azure OpenAI resource. Point it at the resource's OpenAI-compatible v1 endpoint, set the resource's API key, and use your deployment name as the model. This works for both embeddings and completions.

GQL
-- 1. Point the openai provider at the resource's v1 endpoint
RETURN ai.set_base_url("openai", "https://<resource>.openai.azure.com/openai/v1")

-- 2. Set the resource's API key
RETURN ai.set_api_key("openai", "<azure-api-key>")

-- 3. Use the Azure deployment name as the model (not the base model name)
RETURN ai.set_embedding_model("openai", "<embedding-deployment-name>")
RETURN ai.set_completion_model("openai", "<completion-deployment-name>")

The following Azure forms are not supported yet:

The deployment-path URL form (https://<resource>.openai.azure.com/openai/deployments/<deployment>/...?api-version=...). Use the /openai/v1 endpoint shown above instead.
Azure AD (Microsoft Entra ID) token authentication. Use the resource's API key.

Embedding Provider

ai.set_provider()

Sets the active embedding provider. The provider's API key must have been set first via ai.set_api_key().

Syntax	`ai.set_provider(<provider>)`
Arguments	Name	Type	Description
Arguments	`<provider>`	`STRING`	Embedding provider name (see Supported Providers)
Return Type	`BOOL`

GQL
RETURN ai.set_provider("openai")

ai.provider()

Returns the name of the current embedding provider.

Syntax	`ai.provider()`
Arguments	None
Return Type	`STRING`

GQL
RETURN ai.provider()

ai.embed_dim()

Returns the embedding dimension of the current provider. Returns null if no embedding provider is active or the provider doesn't support embedding.

Syntax	`ai.embed_dim()`
Arguments	None
Return Type	`INT`

GQL
RETURN ai.embed_dim()

ai.set_embedding_model()

Overrides the embedding model for a given provider at runtime. The override is persisted and re-activates the affected provider, so subsequent ai.embed(), ai.embed_batch(), and vector-index inserts use the new model immediately.

NOTE

Watch out for dimension changes. Switching models within the same provider often changes the embedding dimension (e.g. OpenAI text-embedding-3-small is 1536-dim, text-embedding-3-large is 3072-dim). When the dimension changes, GQLDB emits a warning that includes the old and new dimensions; existing vector indexes were built for the previous dimension and must be rebuilt with ai.rebuild_index() or query results will silently mismatch.

Syntax	`ai.set_embedding_model(<provider>, <model>)`
Arguments	Name	Type	Description
	`<provider>`	`STRING`	Provider name (see Supported Providers).
	`<model>`	`STRING`	The new embedding model name (provider-specific identifier, e.g. `"text-embedding-3-large"`).
Return Type	`BOOL`

GQL
RETURN ai.set_embedding_model("openai", "text-embedding-3-large")
-- If the dimension changes, rebuild any vector indexes that depended on the old model:
RETURN ai.rebuild_index("summary_embedding")

Completion Provider

ai.set_completion_provider()

Sets the active completion provider. The provider's API key must have been set first via ai.set_api_key().

Syntax	`ai.set_completion_provider(<provider>)`
Arguments	Name	Type	Description
Arguments	`<provider>`	`STRING`	Provider name (see Supported Providers)
Return Type	`BOOL`

GQL
RETURN ai.set_completion_provider("anthropic")

ai.completion_provider()

Returns the name of the current completion provider.

Syntax	`ai.completion_provider()`
Arguments	None
Return Type	`STRING`

GQL
RETURN ai.completion_provider()

ai.set_completion_model()

Overrides the completion model for a given provider at runtime. The override is persisted and re-activates the affected provider, so subsequent ai.gql(), ai.explain(), and other completion calls use the new model immediately.

Use this when you want to switch between models offered by the same provider (e.g. gpt-4o vs gpt-4o-mini on OpenAI, or claude-3-5-sonnet vs claude-3-5-haiku on Anthropic) without re-running ai.set_api_key() or ai.set_completion_provider().

Syntax	`ai.set_completion_model(<provider>, <model>)`
Arguments	Name	Type	Description
	`<provider>`	`STRING`	Provider name (see Supported Providers).
	`<model>`	`STRING`	The new completion model name (provider-specific identifier, e.g. `"gpt-4o"`, `"claude-3-5-sonnet"`).
Return Type	`BOOL`

GQL
RETURN ai.set_completion_model("openai", "gpt-4o")