Find embedding providers

Get information about embedding providers for Astra DB vectorize, including supported providers, models, dimensions, and other configuration parameters.

You need an application token with permission to interact with the target database, such as the Database Administrator role.

For more information, see Get endpoint and token.

Result

Python
TypeScript
Java
curl

Returns:

FindEmbeddingProvidersResult - An object representing the full response from the findEmbeddingProviders Data API command.

The information in the response is arranged as a hierarchy of nested classes, structured like the Data API JSON response. Refer to the following examples or consult the involved classes in the client reference:

Result

# providers list abridged for clarity:
FindEmbeddingProvidersResult(embedding_providers=azureOpenAI, bedrock, cohere, ...)

You can navigate the response by looping, filtering and inspecting nested objects. The actual response depends on the models available for a given database.

Returns:

Promise<FindEmbeddingProvidersResult> - An object representing the full response from the findEmbeddingProviders API command.

Returns:

FindEmbeddingProvidersResult - An object representing the full response from the findEmbeddingProviders API command.

The information in the response is arranged as a hierarchy of nested classes, structured like the API JSON response itself. It wraps a map with provider names as keys and EmbeddingProvider objects as values.

Result

This example response is shortened and edited for clarity.

Provider: openai

+ Authentication Header
  + Token accepted=x-embedding-api-key, forwarded=Authorization
+ Models:
  + Name=text-embedding-3-small
  + Name=text-embedding-3-large
  + Name=text-embedding-ada-002, dimension=1536

Returns:

A successful response returns a JSON object describing the embedding providers and settings available for the specified database.

Result

This example response is shortened and edited for clarity.

{
  "status": {
    "embeddingProviders": {
      "openai": {
        "displayName": "OpenAI",
        "url": "https://api.openai.com/v1/",
        "supportedAuthentication": {
          "SHARED_SECRET": {
            "enabled": true,
            "tokens": [
              {
                "accepted": "providerKey",
                "forwarded": "Authorization"
              }
            ]
          },
          # Truncated
        },
        "parameters": [
          {
            "name": "organizationId",
            "type": "STRING",
            "required": false,
            "defaultValue": "",
            "validation": {},
            "help": "Optional, OpenAI Organization ID. If provided [...]",
            "displayName": "Organization ID",
            "hint": "Add an (optional) organization ID"
          },
          # Truncated
        ],
        "models": [
          {
            "name": "text-embedding-3-small",
            "vectorDimension": null,
            "parameters": [
              {
                "name": "vectorDimension",
                "type": "number",
                "required": true,
                "defaultValue": "1536",
                "validation": {
                  "numericRange": [
                    2,
                    1536
                  ]
                },
                "help": "Vector dimension to use in [...]"
              }
            ]
          },
          # Truncated
        ]
      },
      # Truncated
    }
  }
}

Parameters

Python
TypeScript
Java
curl

embedding_providers = db_admin.find_embedding_providers()

Parameters:

Name Type Summary

Name	Type	Summary
`filter_model_status`	`ModelStatus` or an equivalent string	Filters the available models by status. Default: `ModelStatus.SUPPORTED`
`database_admin_timeout_ms`	`int`	A timeout, in milliseconds, for the underlying HTTP request. If not provided, the Database Admin setting is used. This parameter is aliased as `request_timeout_ms` and `timeout_ms` for convenience.

filter_model_status

ModelStatus or an equivalent string

Filters the available models by status.

Default: ModelStatus.SUPPORTED

database_admin_timeout_ms

int

A timeout, in milliseconds, for the underlying HTTP request. If not provided, the Database Admin setting is used. This parameter is aliased as request_timeout_ms and timeout_ms for convenience.

const embeddingProviders = await dbAdmin.findEmbeddingProviders();

Parameters:

Name Type Summary

Name	Type	Summary
`options`	`FindEmbeddingProvidersOptions`	Optional. The options for this operation. See Properties of `options` for more details.

options

FindEmbeddingProvidersOptions

Optional. The options for this operation. See Properties of options for more details.

Properties of `options`
Name	Type	Summary
`filterModelStatus`	ModelLifecycleStatus \| ""	Filters the available models by status. Default: `SUPPORTED`
`timeout`	`number` \| `TimeoutDescriptor`	Optional. The client-side timeout for this operation.

// Given 'dbAdmin', a DatabaseAdmin object
FindEmbeddingProvidersResult embeddingProviders =
      dbAdmin.findEmbeddingProviders();

Parameters:

Name Type Summary

Name	Type	Summary
`options`	`FindEmbeddingProvidersOptions`	Options for this command, including a filter for the available models by status. By default, the command returns only the supported models.

options

FindEmbeddingProvidersOptions

Options for this command, including a filter for the available models by status. By default, the command returns only the supported models.

Use the findEmbeddingProviders Data API command to get information about embedding providers for vectorize. Don’t include a keyspace in the request URL.

The application token must have sufficient permissions to perform the requested operations, such as the Database Administrator role.

Parameters:

Name Type Summary

Name	Type	Summary
`options.filterModelStatus`	`string`	Optional. Filters the available models by status. Can be one of: `"SUPPORTED"`, `"DEPRECATED"`, `"END_OF_LIFE"`, `""` (no filter). Default: `"SUPPORTED"`

options.filterModelStatus

string

Optional. Filters the available models by status. Can be one of: "SUPPORTED", "DEPRECATED", "END_OF_LIFE", "" (no filter).

Default: "SUPPORTED"

Examples

The following examples demonstrate how to find embedding providers.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
db_admin = client.get_admin().get_database_admin("https://01234567-...")


# The outputs in this snippet are shortened and reformatted for readability:

find_e_p_result = db_admin.find_embedding_providers()
find_e_p_result
#  FindEmbeddingProvidersResult(
#    embedding_providers=..., huggingface, ..., mistral, openai, ...
#  )

find_e_p_result.embedding_providers.keys()
#  dict_keys(['openai', ..., 'huggingface', 'mistral'])

find_e_p_result.embedding_providers['openai']
#  EmbeddingProvider(
#    display_name='OpenAI',
#    models=[
#      EmbeddingProviderModel(name='text-embedding-3-small'),
#      EmbeddingProviderModel(name='text-embedding-3-large'),
#      EmbeddingProviderModel(name='text-embedding-ada-002')
#    ]
#  )

find_e_p_result.embedding_providers['openai'].display_name
#  'OpenAI'

find_e_p_result.embedding_providers['openai'].parameters
#  [
#    EmbeddingProviderParameter(name='organizationId'),
#    EmbeddingProviderParameter(name='projectId')
#  ]

find_e_p_result.embedding_providers['openai'].supported_authentication
#  {
#    'HEADER': EmbeddingProviderAuthentication(
#        enabled=True, tokens=EmbeddingProviderToken('x-embedding-api-key')
#    ),
#    'SHARED_SECRET': EmbeddingProviderAuthentication(
#        enabled=True, tokens=EmbeddingProviderToken('providerKey')
#    ),
#    'NONE': EmbeddingProviderAuthentication(enabled=False, tokens=)
#  }

my_model = find_e_p_result.embedding_providers['openai'].models[1]
my_model
#  EmbeddingProviderModel(name='text-embedding-3-large')

my_model.parameters
#  [EmbeddingProviderParameter(name='vectorDimension')]

my_model.parameters[0].parameter_type
#  'number'

my_model.parameters[0].validation
#  {'numericRange': [256, 3072]}

my_model.parameters[0].default_value
#  '3072'

import { DataAPIClient } from '@datastax/astra-db-ts'

// Spawn an AstraDbAdmin instance
const admin = new DataAPIClient('TOKEN').admin();
const dbAdmin = admin.dbAdmin('ENDPOINT');

(async function () {
  const { embeddingProviders: info } = await dbAdmin.findEmbeddingProviders();

  // { openai: { ... }, huggingface: { ... }, mistral: { ... }, ... }
  console.log(info);

  // ['openai', 'huggingface', 'mistral', ...]
  console.log(Object.keys(info))

  // { displayName: 'OpenAI', parameters: [...], models: [...], ... }
  console.log(info.openai);

  // 'OpenAI'
  console.log(info.openai.displayName);

  // [{ name: 'organizationId', ... }, { name: 'projectId', ... }]
  console.log(info.openai.parameters);

  // { HEADER: { enabled: true, ... }, SHARED_SECRET: { enabled: true, ... }, NONE: { enabled: false, ... } }
  console.log(info.openai.supportedAuthentication);

  // { name: 'text-embedding-3-small', vectorDimension: null, parameters: { ... } }
  console.log(info.openai.models[0]);

  // [{ name: 'vectorDimension', ... }]
  console.log(info.openai.models[0].parameters);

  // 'number'
  console.log(info.openai.models[0].parameters[0].type);

  // { numericRange: [256, 3072] }
  console.log(info.openai.models[0].parameters[0].validation);

  // '3072'
  console.log(info.openai.models[0].parameters[0].defaultValue);
})();

package com.datastax.astra.client.database_admin;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.admin.DatabaseAdmin;
import com.datastax.astra.client.databases.commands.results.FindEmbeddingProvidersResult;
import com.datastax.astra.client.core.vectorize.EmbeddingProvider;
import com.datastax.astra.client.databases.Database;

import java.util.Map;

public class FindEmbeddingProviders {
    public static void main(String[] args) {
        Database db = new DataAPIClient("TOKEN")
                .getDatabase("API_ENDPOINT");
        DatabaseAdmin dbAdmin = db.getDatabaseAdmin();

        // was actually a new object not the initial
        // RATIONAL: as you can come from AstraDBAdmin potentially you not always have a database object created
        Database db1 = dbAdmin.getDatabase();
        Database db2 = dbAdmin.getDatabase("keyspace2");

        FindEmbeddingProvidersResult fepr = db.getDatabaseAdmin().findEmbeddingProviders();

        Map<String, EmbeddingProvider> providers = fepr.getEmbeddingProviders();
        for (Map.Entry<String, EmbeddingProvider> entry : providers.entrySet()) {
            System.out.println("\nProvider: " + entry.getKey());
            EmbeddingProvider provider = entry.getValue();
            provider.getHeaderAuthentication().ifPresent(headerAuthentication -> {
                System.out.println("+ Authentication Header");
                headerAuthentication.getTokens().forEach(token -> {
                    System.out.println("  +"
                            + " Token accepted=" + token.getAccepted()
                            + ", forwarded=" + token.getForwarded());
                });
            });
            System.out.println("+ Models:");
            for(EmbeddingProvider.Model model : provider.getModels()) {
                System.out.println("  + Name=" +
                        model.getName() + ((model.getVectorDimension() != null) ? ", dimension=" + model.getVectorDimension() : ""));
            }
        }
    }
}

curl -sS -L -X POST "API_ENDPOINT/api/json/v1" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "findEmbeddingProviders": {
    "options": {
      "filterModelStatus": "SUPPORTED"
    }
  }
}'

You can use | jq to filter the response:

curl -sS -L -X POST "API_ENDPOINT/api/json/v1" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "findEmbeddingProviders": {
    "options": {
      "filterModelStatus": "SUPPORTED"
    }
  }
}' | jq .status.embeddingProviders.MODEL_NAME

Client reference

Python
TypeScript
Java
curl

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

Find embedding providers

Result

Parameters

Examples

Client reference

Was this helpful?

Give Feedback