Skip to content
👀 Our most exciting product launch yet 🚀 Join us May 8th for Sanity Connect
Experimental feature

Embeddings Index CLI reference

Reference documentation of the Sanity Embeddings Index CLI to create and manage embeddings indexes for your content.

Using this feature requires Sanity to send data to OpenAI and Pinecone to store vector interpretations of documents.

Gotcha

Embeddings Index API is currently in beta. Features and behavior may change without notice.

Embeddings Index API is available to users on the Team plan and above.

Embeddings Index API functionality is available through the Embeddings Index CLI, the Embeddings Index UI for Sanity Studio, and the Embeddings Index HTTP API.

The Sanity Embeddings Index CLI offers commands to create, delete, fetch, and query embeddings indexes in a Sanity project.

You can install the Embeddings Index CLI:

  • Globally, to make its commands available in the terminal regardless of the current directory path.
  • Locally, on a per-project basis.

To execute the commands without installing the Embeddings Index CLI, invoke them through the npx package runner.

The Embeddings Index CLI commands work only in the context of a local Sanity project:

# Go to the root directory of a Sanity project
cd path-to/my-sanity-project/root-dir

# Invoke the embeddings-index CLI commands
embeddings-index-cli <command> [<arguments>]

# Alternatively: invoke the commands without installing
npx @sanity/embeddings-index-cli <command> [<arguments>]

Prerequisites

Installing the Embeddings Index CLI

# Installing the Embeddings Index CLI globally
npm install --global --save-dev @sanity/embeddings-index-cli

# Installing the Embeddings Index CLI for a specific Sanity project
cd path-to/my-sanity-project/root-dir
npm install --save-dev @sanity/embeddings-index-cli

# Running the Embeddings Index CLI commands without installation
npx @sanity/embeddings-index-cli <command> [<arguments>]

Embeddings Index CLI commands

To view the built-in help, run:

# Prints the help for the available commands and arguments
embeddings-index-cli --help

# Alternatively, without installing the CLI
npx @sanity/embeddings-index-cli --help

Commands

  • create

    Creates a new embeddings index in the current Sanity project.
    It requires the following arguments:

    • --indexName: assign a descriptive name to the index.
    • --dataset: specify the name of an existing dataset. This is the target dataset to index.
    • --filter: specify the filtering criteria to include in the index only the selected subset of documents from the database.
      The filter must be a valid GROQ filter without the square brackets that wrap the value assigned to _type.
      Example: _type=='tutorial'
    • --projection: specify the projection criteria to include in the index only the selected subset of properties from the filtered documents.
      The projection must be a valid GROQ projection, including curly brackets.
      Example: {title, author}

    Alternatively, you can create an embeddings index by passing a JSON manifest file with the --manifest argument:

    • --manifest <manifest-file-name>.json

    For more information on creating a JSON manifest file, see the CLI manifest command in this reference.

  • delete

    Deletes an existing embeddings index in the current Sanity project.
    It requires the following argument:

    • --indexName: the name of the index to delete.

    Alternatively, you can specify an existing JSON manifest file instead of indexName:

    • --manifest <manifest-file-name>.json
  • get

    Retrieves status information about a specific embeddings index in the current Sanity project.
    It requires the following argument:

    • --indexName: the name of the index whose status you want to retrieve.

    Alternatively, you can specify an existing JSON manifest file instead of indexName:

    • --manifest <manifest-file-name>.json
  • list

    Gets the status of all existing embeddings indexes in a Sanity project.

  • manifest

    Creates a JSON manifest file with the configuration of an embeddings index, and saves the file to the specified location.

    It requires the following arguments:

    • --out: specify the name of the JSON manifest file and, if necessary, the path to the directory to save it to.
      If you don't specify a path, the JSON manifest file is saved to the current location in the Sanity project.
      Example: <manifest-file-name>.json
    • --indexName: see the same argument under create.
    • --dataset: see the same argument under create.
    • --filter: see the same argument under create.
    • --projection: see the same argument under create.
  • query

    Queries an embeddings index.
    Returns an array of document IDs with their relevance score, based on the queried input string.

    It requires the following arguments:

    • --indexName: the name of the index you want to query
    • --text: enter the content that you want to retrieve from the database using the embeddings index.
      The content can be a string of text or a valid JSON-formatted document.

    Examples

    Query the embeddings index to retrieve relevant documents whose content matches the following text string:

    "This is a song about vegetables."

    Query the embeddings index to retrieve relevant documents whose content matches the following JSON document:

    '{"_type": "lyrics", "title": "Call Any Vegetable"}'

Options

  • --debug

    Prints the stack trace. Useful to inspect errors.

  • --help

    Prints the CLI built-in help.

  • --silent

    Doesn't print any information or warning messages.
    Use either --silent or --verbose. Don't specify both options.

  • --verbose

    Logs extensive information and warning messages.
    Use either --silent or --verbose. Don't specify both options.

  • --version

    Prints the version number of the currently installed embeddings index CLI.

Further reading

Set up an embeddings index and learn more about what embeddings can do for your content

Updated on February 13, 2024

Was this article helpful?