📣
TiDB Cloud Premium is now in public preview. Unlimited growth, instant elasticity, advanced security for enterprise workloads. Try it out →
​
Sign InStart for Free
AI
Developer
Best Practices
API
​
Sign InStart for Free

ti fs update-file-system-embedding-configuration

Enables or disables optional app-managed embedding for one Filesystem. Enabling performs a real provider validation request that can incur a small provider charge. After enablement, text or extracted descriptions are sent to the selected embedding provider.

Syntax

ti fs update-file-system-embedding-configuration
  --enabled <boolean>
  --file-system-id <string>
  [--dry-run]
  [--help]
  [--provider-api-base <string>]
  [--provider-model <string>]
  [--version]

Options

  • --enabled <boolean>: Enter true with a complete provider configuration, or false without provider options. [required]
  • --file-system-id <string>: Set the immutable Filesystem ID. [required]
  • --dry-run: Validate the request without contacting the Filesystem backend or embedding provider.
  • --provider-api-base <string>: Set a valid HTTPS OpenAI-compatible provider base URL.
  • --provider-model <string>: Set an embedding model that returns exactly 1024 dimensions.
  • --help: Display help information.
  • --version: Display version information.

For options shared by all commands, see Global options.

The provider API key is accepted only from TI_FS_AI_PROVIDER_API_KEY. It is sent to the Filesystem backend for validation and encrypted storage, is never stored locally by ti, and is returned only in masked form. Embedding requires an exact OpenAI-compatible /v1/embeddings contract. Native provider interfaces are not supported.

A Filesystem whose source is database_auto uses database-managed embedding and cannot be changed with this command. Do not retry an update blindly after a timeout or lost response. Run the describe command first to determine whether the update succeeded.

Examples

  • Enable app-managed embedding:

    # Read the provider key without echoing it or storing it in shell history.
printf 'Provider API key: ' >&2
read -r -s TI_FS_AI_PROVIDER_API_KEY
printf '\n' >&2
export TI_FS_AI_PROVIDER_API_KEY

# Configure a model that returns exactly 1024 dimensions.
ti fs update-file-system-embedding-configuration \
  --file-system-id <file-system-id> \
  --enabled true \
  --provider-api-base https://api.openai.com/v1 \
  --provider-model text-embedding-3-small
unset TI_FS_AI_PROVIDER_API_KEY

  • Preview enablement without validating or saving the provider:

    # Read the provider key without echoing it or storing it in shell history.
printf 'Provider API key: ' >&2
read -r -s TI_FS_AI_PROVIDER_API_KEY
printf '\n' >&2
export TI_FS_AI_PROVIDER_API_KEY

# Validate local inputs and show a redacted request plan.
ti fs update-file-system-embedding-configuration \
  --file-system-id <file-system-id> \
  --enabled true \
  --provider-api-base https://api.openai.com/v1 \
  --provider-model text-embedding-3-small \
  --dry-run
unset TI_FS_AI_PROVIDER_API_KEY

  • Disable app-managed embedding:

    # Remove custom embedding configuration without changing normal file access.
ti fs update-file-system-embedding-configuration \
  --file-system-id <file-system-id> \
  --enabled false

Was this page helpful?