Databases reference

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

from astrapy import DataAPIClient
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", dimension=5)
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.info.region
# '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.model.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_cursor = admin.list_databases()
database_list = list(database_cursor)
len(database_list)
# 3
database_list[2].id
# '01234567-...'
database_list[2].status
# 'ACTIVE'
database_list[2].info.region
# '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.model.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-...")
# {'ok': 1}
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("01234567-...")

db_admin.list_keyspaces()
# ['default_keyspace']
db_admin.create_keyspace("that_other_one")
# {'ok': 1}
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.Database;

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

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

    // The database can be mutate on keyspace creation
    db.getDatabaseAdmin().createKeyspace("<keyspace2_name>", 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("01234567-...")

db_admin.list_keyspaces()
# ['default_keyspace']
db_admin.create_keyspace("that_other_one")
# {'ok': 1}
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("01234567-...")

db_admin.list_keyspaces()
# ['default_keyspace', 'that_other_one']
db_admin.drop_keyspace("that_other_one")
# {'ok': 1}
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.Database;

public class DropKeyspace {

    public static void main(String[] args) {
        // Default initialization
        Database db = new Database("API_ENDPOINT", "TOKEN");

        // 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("01234567-...")


>>> find_e_p_result = db_admin.find_embedding_providers()
>>> find_e_p_result  # output shortened and reformatted for clarity:
FindEmbeddingProvidersResult(
    embedding_providers=..., huggingface, ..., mistral, openai, ...
)

# output shortened for clarity:
>>> find_e_p_result.embedding_providers.keys()
dict_keys(['openai', ..., 'huggingface', 'mistral'])

# output reformatted for clarity:
>>> 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'

# output reformatted for clarity:
>>> find_e_p_result.embedding_providers['openai'].parameters
[
    EmbeddingProviderParameter(name='organizationId'),
    EmbeddingProviderParameter(name='projectId')
]

# output reformatted for clarity:
>>> 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 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.Database;
import com.datastax.astra.client.admin.DatabaseAdmin;
import com.datastax.astra.client.model.EmbeddingProvider;
import com.datastax.astra.client.model.FindEmbeddingProvidersResult;

import java.util.Map;

public class FindEmbeddingProviders {
    public static void main(String[] args) {
        Database db = new Database("API_ENDPOINT","TOKEN");
        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