Databases reference

new_db_admin = admin.create_database(
    "DATABASE_NAME",
    cloud_provider="PROVIDER",
    region="REGION_NAME",
)

from astrapy import DataAPIClient
from astrapy.info import CollectionDefinition

client = DataAPIClient("TOKEN")
admin = client.get_admin()
new_db_admin = admin.create_database(
    "new_database",
    cloud_provider="aws",
    region="ap-south-1",
)
new_db = new_db_admin.get_database()
collection = new_db.create_collection(
    "movies",
    definition=CollectionDefinition.builder().set_vector_dimension(5).build(),
)
collection.insert_one({
    "title": "The Title",
    "$vector": [0.1, 0.3, -0.7, 0.9, -0.1],
})

const newDbAdmin = await admin.createDatabase({
  name: 'DATABASE_NAME',
  region: 'REGION_NAME',
  cloudProvider: 'PROVIDER',
});

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

// Obtain an admin instance
const admin = new DataAPIClient('TOKEN').admin();

(async function () {
  // Create a new database
  const dbAdmin = await admin.createDatabase({
    name: 'my-database',
    region: 'us-east1',
    cloudProvider: 'GCP',
  });

  // Get and use the database
  const db = dbAdmin.db();
  console.log(await db.listCollections());
})();

// Create a vector database with the specified name and the default options
DatabaseAdmin new_db_admin1 = admin.createDatabase(String name);

// Create a vector database with the specified name, cloud provider, and region
DatabaseAdmin new_db_admin2 = admin.createDatabase(
        String name,
        CloudProviderType cloudProvider,
        String cloudRegion);

// Create a vector database with the specified name, cloud provider, and region
// waitUntilActive determines when the method returns
DatabaseAdmin new_db_admin3 = admin.createDatabase(
        String name,
        CloudProviderType cloudProvider,
        String cloudRegion,
        boolean waitUntilActive);

package com.datastax.astra.client.admin;

import com.datastax.astra.client.DataAPIClient;
import com.dtsx.astra.sdk.db.domain.CloudProviderType;

public class CreateDatabase {
  public static void main(String[] args) {
    AstraDBAdmin astraDBAdmin = new DataAPIClient("TOKEN").getAdmin();

    // Choose a cloud provider (GCP, AZURE, AWS) and a region
    CloudProviderType cloudProvider = CloudProviderType.GCP;
    String cloudRegion = "us-east1";

    // Create a database
    DatabaseAdmin admin = astraDBAdmin.createDatabase("DATABASE_NAME", cloudProvider, cloudRegion);
  }
}

curl -sS -L -X POST "https://api.astra.datastax.com/v2/databases" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "name": "DATABASE_NAME",
  "keyspace": "",
  "cloudProvider": "CLOUD_PROVIDER",
  "region": "REGION",
  "dbType": "vector",
  "tier": "serverless",
  "capacityUnits": 1
}'

astra db create DB_NAME --region REGION --cloud CLOUD_PROVIDER \
-k KEYSPACE --if-not-exist --async

db_info = admin.database_info("DB_ID")

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
admin = client.get_admin()

db_details = admin.database_info("01234567-...")
db_details.id
# '01234567-...'
db_details.status
# 'ACTIVE'
db_details.regions[0].region_name
# 'eu-west-1'

const dbInfo = admin.dbInfo('DB_ID');

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

const admin = new DataAPIClient('TOKEN').admin();

(async function () {
  const details = await admin.dbInfo('DB_ID');
  console.log(details.id); // '01234567-...'
  console.log(details.status); // 'ACTIVE'
  console.log(details.info.region); // 'eu-west-1'
})();

// Given 'admin', a AstraDBAdmin object
admin.getDatabaseInfo(UUID databaseId);

package com.datastax.astra.client.admin;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.databases.definition.DatabaseInfo;

import java.util.UUID;

public class GetDatabaseInformation {
  public static void main(String[] args) {

    AstraDBAdmin astraDBAdmin = new DataAPIClient("TOKEN").getAdmin();

    // Check if a database exists
    boolean exists1 = astraDBAdmin.databaseExists("database_name");
    boolean exists2 = astraDBAdmin.databaseExists(UUID.fromString("<database_id>"));

    // Find a database by name (names may not be unique)
    DatabaseInfo databaseInformation = astraDBAdmin
            .getDatabaseInfo(UUID.fromString("<database_id>"));
    System.out.println("Name=" + databaseInformation.getName());
  }
}

curl -sS -L -X GET "https://api.astra.datastax.com/v2/databases/DB_ID" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

astra db describe DB_ID

all_databases = admin.list_databases()

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
admin = client.get_admin()

database_list = admin.list_databases()
len(database_list)
# 3
database_list[2].id
# '01234567-...'
database_list[2].status
# 'ACTIVE'
database_list[2].regions[0].region_name
# 'eu-west-1'

const dbs = await admin.listDatabases();

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

const admin = new DataAPIClient('TOKEN').admin();

(async function () {
  const activeDbs = await admin.listDatabases({ include: 'ACTIVE' });

  for (const db of activeDbs) {
    console.log(`Database ${db.name} is active`);
  }
})();

// Given 'admin' a AstraDBAdmin object
List<DatabaseInfo> infoList = admin.listDatabases();

package com.datastax.astra.client.admin;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.databases.definition.DatabaseInfo;

public class ListDatabases {
    public static void main(String[] args) {
        
        // Initialization of admin (astra only)
        AstraDBAdmin astraDBAdmin = new DataAPIClient("TOKEN").getAdmin();

        // Display all database information
        astraDBAdmin.listDatabases().stream()
                .map(DatabaseInfo::getId)
                .forEach(System.out::println);

        // Display all database names
        astraDBAdmin.listDatabaseNames();
    }
}

curl -sS -L -X GET "https://api.astra.datastax.com/v2/databases" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

astra db list

admin.drop_database("DB_ID")

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
admin = client.get_admin()

database_list_pre = list(admin.list_databases())
len(database_list_pre)
# 3
admin.drop_database("01234567-...")
# the 'drop_database' method will take some time ...

database_list_post = list(admin.list_databases())
len(database_list_post)
# 2

await admin.dropDatabase('DB_ID');

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

const admin = new DataAPIClient('TOKEN').admin();

(async function () {
  await admin.dropDatabase('DB_ID');
})();

// Given 'admin', a AstraDBAdmin object
// Delete an existing database by name
admin.dropDatabase(String name);

// Delete an existing database by ID
admin.dropDatabase(UUID id);

package com.datastax.astra.client.admin;

import com.datastax.astra.client.DataAPIClient;

import java.util.UUID;

public class DropDatabase {
  public static void main(String[] args) {
    AstraDBAdmin astraDBAdmin = new DataAPIClient("TOKEN").getAdmin();

    // Delete an existing database
    astraDBAdmin.dropDatabase("<database_name>");

    // Delete an existing database by ID
    astraDBAdmin.dropDatabase(UUID.fromString("<database_id>"));

  }
}

curl -sS -L -X POST "https://api.astra.datastax.com/v2/databases/DB_ID/terminate" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

astra db delete DB_ID

db_admin.create_keyspace("KEYSPACE_NAME")

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

db_admin.list_keyspaces()
# ['default_keyspace']
db_admin.create_keyspace("that_other_one")
# this 'create_keyspace' method call takes a few seconds ...
db_admin.list_keyspaces()
# ['default_keyspace', 'that_other_one']

await dbAdmin.createKeyspace('KEYSPACE_NAME');

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

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

(async function () {
  // ['default_keyspace']
  console.log(await dbAdmin.listKeyspaces());

  await dbAdmin.createKeyspace('that_other_one');

  // ['default_keyspace', 'that_other_one']
  console.log(await dbAdmin.listKeyspaces());
})();

// Given 'dbAdmin', a DatabaseAdmin object
void dbAdmin.createKeyspace("new_keyspace");

// Given 'dbAdmin', also change the associated `database` object
void dbAdmin.createKeyspace("new_keyspace", true);

package com.datastax.astra.client.database_admin;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.databases.commands.options.CreateKeyspaceOptions;
import com.datastax.astra.client.databases.definition.keyspaces.KeyspaceDefinition;

public class CreateKeyspace {
  public static void main(String[] args) {
    // Default initialization
    Database db = new DataAPIClient("TOKEN").getDatabase("API_ENDPOINT");

    // Create a new keyspace
    db.getDatabaseAdmin().createKeyspace("<keyspace_name>");

    // The database can be mutate on keyspace creation
    db.getDatabaseAdmin().createKeyspace(
            new KeyspaceDefinition().name("<keyspace2_name>"),
            new CreateKeyspaceOptions().updateDBKeyspace(true));
  }
}

curl -sS -L -X POST "https://api.astra.datastax.com/v2/databases/DB_ID/keyspaces/KEYSPACE_NAME" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

astra db create-keyspace DB_ID -k KEYSPACE_NAME

keyspaces = db_admin.list_keyspaces()

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

db_admin.list_keyspaces()
# ['default_keyspace']
db_admin.create_keyspace("that_other_one")
# this 'create_keyspace' method call takes a few seconds ...
db_admin.list_keyspaces()
# ['default_keyspace', 'that_other_one']

const keyspaces = await dbAdmin.listKeyspaces();

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

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

(async function () {
  // ['default_keyspace']
  console.log(await dbAdmin.listKeyspaces());

  await dbAdmin.createKeyspace('that_other_one');

  // ['default_keyspace', 'that_other_one']
  console.log(await dbAdmin.listKeyspaces());
})();

// Given 'dbAdmin', a DatabaseAdmin object
Set<String> names = dbAdmin.listKeyspaceNames();

package com.datastax.astra.client.database_admin;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.admin.AstraDBAdmin;
import com.datastax.astra.client.admin.DatabaseAdmin;

import java.util.Set;
import java.util.UUID;

public class ListKeyspaces {
    public static void main(String[] args) {

        DataAPIClient client = new DataAPIClient("TOKEN");

        // Accessing admin providing a new token possibly with stronger permissions
        AstraDBAdmin admin = client.getAdmin("SUPER_USER_TOKEN");

        DatabaseAdmin dbAdmin = admin.getDatabaseAdmin(UUID.fromString("DATABASE_ID"));

        // List available keyspaces
        Set<String> names = dbAdmin.listKeyspaceNames();
    }
}

astra db list-keyspaces DB_ID

db_admin.drop_keyspace("KEYSPACE_NAME")

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

db_admin.list_keyspaces()
# ['default_keyspace', 'that_other_one']
db_admin.drop_keyspace("that_other_one")
# the 'drop_keyspace' method call takes a few seconds ...
db_admin.list_keyspaces()
# ['default_keyspace']

await dbAdmin.dropKeyspace('KEYSPACE_NAME');

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

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

(async function () {
  // ['default_keyspace', 'that_other_one']
  console.log(await dbAdmin.listKeyspaces());

  await dbAdmin.dropKeyspace('that_other_one');

  // ['default_keyspace']
  console.log(await dbAdmin.listKeyspaces());
})();

// Given 'dbAdmin', a DatabaseAdmin object
void dbAdmin.dropKeyspace("KEYSPACE_NAME");

package com.datastax.astra.client.database_admin;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.databases.Database;

public class DropKeyspace {

    public static void main(String[] args) {
        // Default initialization
        Database db = new DataAPIClient("TOKEN")
                .getDatabase("API_ENDPOINT");
        // Drop a Namespace
        db.getDatabaseAdmin().dropKeyspace("<keyspace_name>");
    }
}

curl -sS -L -X DELETE "https://api.astra.datastax.com/v2/databases/DB_ID/keyspaces/KEYSPACE_NAME" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

astra db delete-keyspace DB_ID -k KEYSPACE_NAME

embedding_providers = db_admin.find_embedding_providers()

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'

const embeddingProviders = await dbAdmin.findEmbeddingProviders();

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);
})();

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

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 "ASTRA_DB_API_ENDPOINT/api/json/v1" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "findEmbeddingProviders": {}
}'

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

reranking_providers = db_admin.find_reranking_providers()

find_r_p_result = db_admin.find_reranking_providers()
find_r_p_result
#  FindRerankingProvidersResult(reranking_providers=nvidia)

find_r_p_result.reranking_providers.keys()
#  dict_keys(['nvidia'])

find_r_p_result.reranking_providers['nvidia']
#  RerankingProvider(
#    <Default> display_name='Nvidia',
#    models=[
#      RerankingProviderModel(
#        <Default> name='nvidia/llama-3.2-nv-rerankqa-1b-v2'
#      )
#    ]
#  )

find_r_p_result.reranking_providers['nvidia'].display_name
#  'Nvidia'

find_r_p_result.reranking_providers['nvidia'].is_default
#  True

find_r_p_result.reranking_providers['nvidia'].parameters
#  []

find_r_p_result.reranking_providers['nvidia'].supported_authentication
#  {'NONE': RerankingProviderAuthentication(enabled=True, tokens=)}

my_model = find_r_p_result.reranking_providers['nvidia'].models[0]
my_model
#  RerankingProviderModel(
#    <Default> name='nvidia/llama-3.2-nv-rerankqa-1b-v2'
#  )

my_model.is_default
#  True

my_model.parameters
#  []

const rerankingProviders = await dbAdmin.findRerankingProviders();

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 { rerankingProviders: info } = await dbAdmin.findRerankingProviders();

  // { nvidia: { ... }, ... }
  console.log(info);

  // ['nvidia', ...]
  console.log(Object.keys(info))

  // { displayName: 'Nvidia', models: [...], ... }
  console.log(info.nvidia);

  // 'Nvidia'
  console.log(info.nvidia.displayName);

  // true
  console.log(info.nvidia.isDefault);

  // []
  console.log(info.nvidia.parameters);

  // { NONE: { enabled: true, ... } }
  console.log(info.nvidia.supportedAuthentication);

  // { name: 'nvidia/llama-3.2-nv-rerankqa-1b-v2', parameters: [] }
  console.log(info.nvidia.models[0]);

  // true
  console.log(info.nvidia.models[0].isDefault);

  // []
  console.log(info.nvidia.models[0].parameters);
})();

FindRerankingProvidersResult findRerankingProviders();

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.admin.DatabaseAdmin;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.databases.commands.results.FindRerankingProvidersResult;

public class FindRerankingProviders {

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

   DatabaseAdmin dbAdmin = db
     .getDatabaseAdmin();

   FindRerankingProvidersResult results = dbAdmin
     .findRerankingProviders();

   results.getRerankingProviders().forEach((name, provider) -> {;
     System.out.println("Provider: " + name);
     System.out.println("Display Name: " + provider.getDisplayName());
     System.out.println("Is Default: " + provider.getIsDefault());
     System.out.println("Parameters: " + provider.getParameters());
     System.out.println("Supported Authentication: " + provider.getSupportedAuthentication());
     System.out.println("Models: " + provider.getModels());
   });
  }
}

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "findRerankingProviders": {}
}'

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "findRerankingProviders": {}
}' | jq .status.rerankingProviders.MODEL_NAME