Manage Astra DB with the Astra CLI
Use the Astra CLI to manage your Astra DB deployments.
|
You can use |
Create a database
Use the astra db create command to create a new Serverless (Non-Vector) database:
astra db create DATABASE_NAMEResult
[INFO] Database 'my_serverless_db' does not exist. Creating database 'my_serverless_db' with keyspace 'default_keyspace'
[INFO] Database 'my_serverless_db' and keyspace 'default_keyspace' are being created.
[INFO] Database 'my_serverless_db' has status 'PENDING' waiting to be 'ACTIVE' ...
[INFO] Database 'my_serverless_db' has status 'ACTIVE' (took 470346 millis)
[OK] Database 'my_serverless_db' is ready.Use the --vector option to create a Serverless (Vector) database:
astra db create DATABASE_NAME --vectorResult
[INFO] Database 'my_vector_db' does not exist. Creating database 'my_vector_db' with keyspace 'default_keyspace'
[INFO] Enabling vector search for database my_vector_db
[INFO] Database 'my_vector_db' and keyspace 'default_keyspace' are being created.
[INFO] Database 'my_vector_db' has status 'PENDING' waiting to be 'ACTIVE' ...
[INFO] Database 'my_vector_db' has status 'ACTIVE' (took 142712 millis)
[OK] Database 'my_vector_db' is ready.|
You cannot create Classic databases with the Astra CLI. However, you can use the Astra CLI to get information about existing Classic databases. |
Running astra db create without any options deploys the database in an available Free region and uses default_keyspace as the name for the default keyspace.
If the database already exists but is currently hibernated, the astra db create command resumes the database.
By default, the command runs synchronously and doesn’t return the command prompt until the database reaches Active or Error status.
To run the command asynchronously, add the --async option.
db create options
Expand to see all db create options
NAME
astra db create - Create a database with cli
SYNOPSIS
astra db create [ --async ] [ {-c | --cloud} <cloud> ]
[ --capacity-units <CAPACITY UNITS> ]
[ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ {--if-not-exist | --if-not-exists} ]
[ {-k | --keyspace} <KEYSPACE> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] [ {-r | --region} <DB_REGION> ]
[ --tier <TIER> ] [ --timeout <timeout> ]
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [ --vector ] [--]
<DB>
OPTIONS
--async
Will not wait for the resource to become available
-c <cloud>, --cloud <cloud>
Cloud Provider to create a db
--capacity-units <CAPACITY UNITS>
Capacity units to create the database with (default 1)
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--if-not-exist, --if-not-exists
will create a new DB only if none with same name
-k <KEYSPACE>, --keyspace <KEYSPACE>
Default keyspace created with the Db
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
-r <DB_REGION>, --region <DB_REGION>
Cloud provider region to provision
--tier <TIER>
Tier to create the database in
--timeout <timeout>
Provide a limit to the wait period in seconds, default is 300s.
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--vector
Create a database with vector search enabled
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierUse the -c, -r, and -k options to specify the cloud provider, region, and keyspace name when creating a database:
astra db create DATABASE_NAME \
-c CLOUD_PROVIDER \
-r REGION \
-k KEYSPACE_NAMEResult
[INFO] Database 'my_serverless_db' does not exist. Creating database 'my_serverless_db' with keyspace 'my_keyspace'
[INFO] Database 'my_serverless_db' and keyspace 'my_keyspace' are being created.
[INFO] Database 'my_serverless_db' has status 'PENDING' waiting to be 'ACTIVE' ...
[INFO] Database 'my_serverless_db' has status 'ACTIVE' (took 109050 millis)
[OK] Database 'my_serverless_db' is ready.Manage keyspaces
Astra DB databases store data in collections and tables, which exist inside keyspaces. Each database must have at least one keyspace, and you can create more as needed.
Use the astra db create-keyspace command to create a new keyspace in a database:
astra db create-keyspace DATABASE_ID -k KEYSPACE_NAMEResult
[INFO] Keyspace 'keyspace2' is creating.
[INFO] Database '26054aa9-eb37-4d88-b343-7c934cd1d7bc' has status 'MAINTENANCE' waiting to be 'ACTIVE' ...
[INFO] Database 'my_serverless_db' has status 'ACTIVE' (took 6669 millis)
[OK] Database '26054aa9-eb37-4d88-b343-7c934cd1d7bc' is ready.
[OK] Database '26054aa9-eb37-4d88-b343-7c934cd1d7bc' is ready.The database enters Maintenance status while creating the keyspace. When the database returns to Active status, you can use the new keyspace.
By default, the command runs synchronously and doesn’t return the command prompt until the database reaches Active or Error status.
To run the command asynchronously, add the --async option.
|
By default, the Astra CLI returns an error if a keyspace with the same name already exists.
However, if you use the Result |
Use the astra db list-keyspaces command to get a list of the keyspaces in a database:
astra db list-keyspaces DATABASE_IDResult
+---------------------+
| Name |
+---------------------+
| keyspace1 (default) |
| keyspace2 |
+---------------------+Use the astra db delete-keyspace command to delete a keyspace from a database:
astra db delete-keyspace DATABASE_ID -k KEYSPACE_NAMEResult
[INFO] Database '26054aa9-eb37-4d88-b343-7c934cd1d7bc' has status 'MAINTENANCE' waiting to be 'ACTIVE' ...
[INFO] Database 'my_serverless_db' has status 'ACTIVE' (took 6804 millis)
[OK] Database '26054aa9-eb37-4d88-b343-7c934cd1d7bc' is ready.|
Deleting a keyspace permanently deletes all collections, tables, and data in the keyspace. |
The database enters Maintenance status while it deletes the keyspace along with any collections, tables, and data within the keyspace.
By default, the command runs synchronously and doesn’t return the command prompt until the database reaches Active or Error status.
To run the command asynchronously, add the --async option.
If you delete the default keyspace, Astra DB automatically selects another keyspace to be the default keyspace.
db create-keyspace options
Expand to see all db create-keyspace options
NAME
astra db create-keyspace - Create a new keyspace
SYNOPSIS
astra db create-keyspace [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --if-not-exist ] {-k | --keyspace} <KEYSPACE> [ --no-color ]
[ {-o | --output} <FORMAT> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [ --wait ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--if-not-exist
will create a new DB only if none with same name
-k <KEYSPACE>, --keyspace <KEYSPACE>
Name of the keyspace to create
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--wait
Will wait until the database become ACTIVE
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb list-keyspaces options
Expand to see all db list-keyspaces options
NAME
astra db list-keyspaces - Display the list of Keyspaces in an database
SYNOPSIS
astra db list-keyspaces [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --no-color ] [ {-o | --output} <FORMAT> ]
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb delete-keyspace options
Expand to see all db delete-keyspace options
NAME
astra db delete-keyspace - Delete an existing keyspace
SYNOPSIS
astra db delete-keyspace [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
{-k | --keyspace} <KEYSPACE> [ --no-color ]
[ {-o | --output} <FORMAT> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-k <KEYSPACE>, --keyspace <KEYSPACE>
Name of the keyspace to create
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierManage collections
Collections store semi-structured data, in the form of documents, in Serverless (Vector) databases.
When you create a collection, you decide if the collection can store structured vector data. This is known as a vector-enabled collection. For vector-enabled collections, you also decide how to provide embeddings. You can bring your own embeddings and automatically generate embeddings with vectorize. You must decide which options you need when you create the collection.
Use the astra db create-collection command to create a new collection in a Serverless (Vector) database:
-
Bring my own embeddings
-
Use an Astra-hosted provider
-
Use an external provider
Use this option if you plan to generate your own embeddings and import them when you load data into your collection.
astra db create-collection DATABASE_ID \
-c COLLECTION_NAME \
-d DIMENSION \
-m SIMILARITY_METRICReplace the following:
-
COLLECTION_NAME: The name of the collection you want to create. -
DIMENSION: The number of dimensions for the vectors in your dataset. -
(Optional)
SIMILARITY_METRIC: The similarity metric that your embedding model will use to compare vectors. The available metrics arecosine(default),dot_product, andeuclidean.
Example:
astra db create-collection 58747660-464b-4085-bef2-c3f3e5401e3d \
-c my_collection \
-d 1024 \
-m dot_productResult
[OK] Collection 'my_collection' as been created from db '58747660-464b-4085-bef2-c3f3e5401e3d' on keyspace 'default_keyspace'
[OK] Database '58747660-464b-4085-bef2-c3f3e5401e3d' is ready.|
To create a collection that is not vector-enabled, omit the ResultYou can’t load vector data into a non-vector collection. |
To automatically generate embeddings with Astra DB vectorize, add an embedding provider integration to your collection. Embedding provider integrations are either Astra-hosted or external.
astra db create-collection DATABASE_ID \
-c COLLECTION_NAME \
--embedding-provider PROVIDER_NAME \
--embedding-model MODEL_NAME \
-d DIMENSION \
-m SIMILARITY_METRICReplace the following:
-
COLLECTION_NAME: The name of the collection you want to create. -
PROVIDER_NAME: The name of the Astra-hosted embedding provider. -
MODEL_NAME: The name of the embedding model that you want to use to generate embeddings. -
(Optional)
DIMENSION: The number of dimensions that you want the generated vectors to have. You can only set the dimensions if the chosen model supports a range of dimensions. -
(Optional)
SIMILARITY_METRIC: The similarity metric that your embedding model will use to compare vectors. The available metrics arecosine(default),dot_product, andeuclidean.
Example:
astra db create-collection 58747660-464b-4085-bef2-c3f3e5401e3d \
-c my_collection \
--embedding-provider nvidia \
--embedding-model NV-Embed-QA \
-d 1024 \
-m dot_productResult
[OK] Collection 'my_collection' as been created from db '58747660-464b-4085-bef2-c3f3e5401e3d' on keyspace 'default_keyspace'
[OK] Database '58747660-464b-4085-bef2-c3f3e5401e3d' is ready.To automatically generate embeddings with Astra DB vectorize, add an embedding provider integration to your collection. Embedding provider integrations are either Astra-hosted or external.
To use an external embedding provider, you must add an embedding provider integration to your Astra DB organization, and then you can select that embedding provider when you create a collection.
astra db create-collection DATABASE_ID \
-c COLLECTION_NAME \
--embedding-provider PROVIDER_NAME \
--embedding-model MODEL_NAME \
--embedding-key PROVIDER_KEY_NAME \
-d DIMENSION \
-m SIMILARITY_METRICReplace the following:
-
COLLECTION_NAME: The name of the collection you want to create. -
PROVIDER_NAME: The name of the Astra-hosted embedding provider. -
MODEL_NAME: The name of the embedding model that you want to use to generate embeddings. -
(Optional)
PROVIDER_KEY_NAME: The name of the provider key that you want to use to authenticate with the external embedding provider. -
(Optional)
DIMENSION: The number of dimensions that you want the generated vectors to have. You can only set the dimensions if the chosen model supports a range of dimensions. -
(Optional)
SIMILARITY_METRIC: The similarity metric that your embedding model will use to compare vectors. The available metrics arecosine(default),dot_product, andeuclidean.
Example:
astra db create-collection 58747660-464b-4085-bef2-c3f3e5401e3d \
-c my_collection \
--embedding-provider openai \
--embedding-model text-embedding-3-small \
--embedding-key my_openai_key \
-d 1024 \
-m dot_productResult
[OK] Collection 'my_collection' as been created from db '58747660-464b-4085-bef2-c3f3e5401e3d' on keyspace 'default_keyspace'
[OK] Database '58747660-464b-4085-bef2-c3f3e5401e3d' is ready.Use the astra db list-collections command to get a list of the collections in default_keyspace:
astra db list-collections DATABASE_IDResult
+---------------------+-----------+-------------------+--------------------+--------------+------------------------+
| Name | DefaultId | Vector Dimension | Similarity Metric | AI Provider | AI Model |
+---------------------+-----------+-------------------+--------------------+--------------+------------------------+
| my_collection | default | 1024 | dot_product | | |
| my_collection2 | default | 1024 | dot_product | nvidia | NV-Embed-QA |
| my_collection3 | default | 1024 | dot_product | openai | text-embedding-3-small |
+---------------------+-----------+-------------------+--------------------+--------------+------------------------+Use the astra db describe-collection command to get information about a specific collection:
astra db describe-collection DATABASE_ID -c COLLECTION_NAMEResult
+-------------------+-----------------------------------------+
| Attribute | Value |
+-------------------+-----------------------------------------+
| Name | my_collection |
| Estim. Count | 0 |
| | |
| Vector: | |
| Vector Dimension | 1024 |
| Similarity Metric | dot_product |
+-------------------+-----------------------------------------+
[OK] Database '58747660-464b-4085-bef2-c3f3e5401e3d' is ready.Use the astra db truncate-collection command to clear an existing collection:
astra db truncate-collection DATABASE_ID -c COLLECTION_NAMEResult
[OK] Collection 'my_collection' as been truncated from '58747660-464b-4085-bef2-c3f3e5401e3d'.Use the astra db delete-collection command to delete a collection:
astra db delete-collection DATABASE_ID -c COLLECTION_NAMEResult
[OK] Collection 'my_collection' as been deleted from '58747660-464b-4085-bef2-c3f3e5401e3d'.
[OK] Database '58747660-464b-4085-bef2-c3f3e5401e3d' is ready.db create-collection options
Expand to see all db create-collection options
NAME
astra db create-collection - Create a new collection
SYNOPSIS
astra db create-collection {-c | --collection} <COLLECTION>
[ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ]
[ {-d | --dimension} <DIMENSION> ]
[ --default-id <DEFAULT_ID> ]
[ --embedding-key <EMBEDDING_KEY> ]
[ --embedding-model <EMBEDDING_MODEL> ]
[ --embedding-provider <EMBEDDING_PROVIDER> ]
[ --env <Environment> ] [ --if-not-exists ]
[ --indexing-allow <INDEXING_ALLOW> ]
[ --indexing-deny <INDEXING_DENY> ]
[ {-k | --keyspace} <KEYSPACE> ] [ {-m | --metric} <METRIC> ]
[ --no-color ] [ {-o | --output} <FORMAT> ]
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [--] <DB>
OPTIONS
-c <COLLECTION>, --collection <COLLECTION>
Name of the collection to create
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
-d <DIMENSION>, --dimension <DIMENSION>
Name of the collection to create
--default-id <DEFAULT_ID>
Default identifier to use for the collection
--embedding-key <EMBEDDING_KEY>
Using Vectorize, embedding key used for shared secret
--embedding-model <EMBEDDING_MODEL>
Using Vectorize, embedding mode to use
--embedding-provider <EMBEDDING_PROVIDER>
Using Vectorize, embedding provider to use
--env <Environment>
Astra Environment to use
--if-not-exists
will create a new collection only if none with same name
--indexing-allow <INDEXING_ALLOW>
List of attribute to add into index (comma separated)
--indexing-deny <INDEXING_DENY>
List of attribute to remove from index (comma separated)
-k <KEYSPACE>, --keyspace <KEYSPACE>
Name of the keyspace to create the collection
-m <METRIC>, --metric <METRIC>
Name of the collection to create
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierUse the -k / --keyspace option to create a collection in a specific keyspace:
astra db create-collection DATABASE_ID \
-k KEYSPACE_NAME \
-c COLLECTION_NAME \
-d DIMENSIONResult
[OK] Collection 'my_collection' as been created from db '58747660-464b-4085-bef2-c3f3e5401e3d' on keyspace 'my_keyspace'
[OK] Database '58747660-464b-4085-bef2-c3f3e5401e3d' is ready.db list-collections options
Expand to see all db list-collections options
NAME
astra db list-collections - Display the list of collections in an
database
SYNOPSIS
astra db list-collections [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ {-k | --keyspace} <KEYSPACE> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-k <KEYSPACE>, --keyspace <KEYSPACE>
Name of the keyspace to create the collection
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierUse the -k / --keyspace option to get a list of the collections in a specific keyspace:
astra db list-collections DATABASE_ID -k KEYSPACE_NAMEResult
+--------------------------+-----------+-------------------+--------------------+--------------+---------------------+
| Name | DefaultId | Vector Dimension | Similarity Metric | AI Provider | AI Model |
+--------------------------+-----------+-------------------+--------------------+--------------+---------------------+
| my_collection | default | 1024 | cosine | | |
| my_collection_non_vector | default | | | | |
+--------------------------+-----------+-------------------+--------------------+--------------+---------------------+db describe-collection options
Expand to see all db describe-collection options
NAME
astra db describe-collection - Describe an existing collection
SYNOPSIS
astra db describe-collection {-c | --collection} <COLLECTION>
[ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ {-k | --keyspace} <KEYSPACE> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [--] <DB>
OPTIONS
-c <COLLECTION>, --collection <COLLECTION>
Name of the collection
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-k <KEYSPACE>, --keyspace <KEYSPACE>
Name of the keyspace to create the collection
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierUse the -k / --keyspace option to get information about a collection in a specific keyspace:
astra db describe-collection DATABASE_ID \
-k KEYSPACE_NAME \
-c COLLECTION_NAMEResult
+-------------------+-----------------------------------------+
| Attribute | Value |
+-------------------+-----------------------------------------+
| Name | my_collection |
| Estim. Count | 0 |
| | |
| Vector: | |
| Vector Dimension | 1024 |
| Similarity Metric | cosine |
+-------------------+-----------------------------------------+
[OK] Database '58747660-464b-4085-bef2-c3f3e5401e3d' is ready.db truncate-collection options
Expand to see all db truncate-collection options
NAME
astra db truncate-collection - Clear an existing collection
SYNOPSIS
astra db truncate-collection {-c | --collection} <COLLECTION>
[ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ {-k | --keyspace} <KEYSPACE> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [--] <DB>
OPTIONS
-c <COLLECTION>, --collection <COLLECTION>
Name of the collection
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-k <KEYSPACE>, --keyspace <KEYSPACE>
Name of the keyspace to clear the table
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierUse the -k / --keyspace option to clear an existing collection in a specific keyspace:
astra db truncate-collection DATABASE_ID \
-k KEYSPACE_NAME \
-c COLLECTION_NAMEResult
[OK] Collection 'my_collection' as been truncated from '58747660-464b-4085-bef2-c3f3e5401e3d'.db delete-collection options
Expand to see all db delete-collection options
NAME
astra db delete-collection - Delete an existing collection
SYNOPSIS
astra db delete-collection {-c | --collection} <COLLECTION>
[ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --if-exists ] [ {-k | --keyspace} <KEYSPACE> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [--] <DB>
OPTIONS
-c <COLLECTION>, --collection <COLLECTION>
Name of the collection to delete
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--if-exists
will delete the collection only if it exists
-k <KEYSPACE>, --keyspace <KEYSPACE>
Name of the keyspace to create the collection
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierUse the -k / --keyspace option to delete a collection from a specific keyspace:
astra db delete-collection DATABASE_ID \
-k KEYSPACE_NAME \
-c COLLECTION_NAMEResult
[OK] Collection 'my_collection' as been deleted from '58747660-464b-4085-bef2-c3f3e5401e3d'.
[OK] Database '58747660-464b-4085-bef2-c3f3e5401e3d' is ready.Manage tables
Tables store structured data, in the form of rows, in Serverless (Vector) and Serverless (Non-Vector) databases.
|
The commands described in this section apply only to Serverless (Vector) databases. |
Use the astra db list-tables command to get a list of the tables in a Serverless (Vector) database:
astra db list-tables DATABASE_IDResult
+---------------------+
| Name |
+---------------------+
| students |
+---------------------+Use the astra db describe-table command to get information about a specific table:
astra db describe-table DATABASE_ID -t TABLE_NAMEResult
+------------------+-----------------------------------------+
| Attribute | Value |
+------------------+-----------------------------------------+
| Name | students |
| | |
| COLUMNS | |
| email | TEXT |
| extracurriculars | SET<TEXT> |
| grades | MAP<TEXT, INT> |
| graduated | BOOLEAN |
| graduation_year | INT |
| name | TEXT |
| semester_gpas | LIST<DECIMAL> |
| vect_emb | VECTOR<FLOAT,1024> |
| | |
| PRIMARY KEY | |
| Partition Key | [0] email |
+------------------+-----------------------------------------+Use the astra db truncate-table command to clear an existing table:
astra db truncate-table DATABASE_ID -t TABLE_NAMEResult
[OK] Table 'students' as been truncated from '58747660-464b-4085-bef2-c3f3e5401e3d'.Use the astra db delete-collection command to delete a collection from a a Serverless (Vector) database:
astra db delete-table DATABASE_ID -t TABLE_NAMEResult
[OK] Table 'students' as been deleted from '58747660-464b-4085-bef2-c3f3e5401e3d'.
[OK] Database '58747660-464b-4085-bef2-c3f3e5401e3d' is ready.db list-tables options
Expand to see all db list-tables options
NAME
astra db list-tables - Display the list of tables in a
database/keyspace couple
SYNOPSIS
astra db list-tables [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ {-k | --keyspace} <KEYSPACE> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-k <KEYSPACE>, --keyspace <KEYSPACE>
Name of the keyspace
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb describe-table options
Expand to see all db describe-table options
NAME
astra db describe-table - Describe an existing table
SYNOPSIS
astra db describe-table [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ {-k | --keyspace} <KEYSPACE> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] {-t | --table} <TABLE>
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-k <KEYSPACE>, --keyspace <KEYSPACE>
Name of the keyspace to create the collection
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
-t <TABLE>, --table <TABLE>
Name of the table
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb truncate-table options
Expand to see all db truncate-table options
NAME
astra db truncate-table - Clear an existing table
SYNOPSIS
astra db truncate-table [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ {-k | --keyspace} <KEYSPACE> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] {-t | --table} <TABLE>
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-k <KEYSPACE>, --keyspace <KEYSPACE>
Name of the keyspace to clear the table
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
-t <TABLE>, --table <TABLE>
Name of the table
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb delete-table options
Expand to see all db delete-table options
NAME
astra db delete-table - Delete an existing table
SYNOPSIS
astra db delete-table [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --if-exists ] [ {-k | --keyspace} <KEYSPACE> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] {-t | --table} <TABLE>
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--if-exists
will delete the table only if it exists
-k <KEYSPACE>, --keyspace <KEYSPACE>
Name of the keyspace to delete the table
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
-t <TABLE>, --table <TABLE>
Name of the table
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierManage embedding providers
Use the astra db list-embedding-providers command to get a list of the embedding provider integrations that are available for a Serverless (Vector) database:
astra db list-embedding-providers DATABASE_IDResult
+----------------------+--------------------------+--------+------------+---------+----------+
| Key | DisplayName | Models | Parameters | Au.Head | S.Secret |
+----------------------+--------------------------+--------+------------+---------+----------+
| cohere | Cohere | 3 | 0 | ■ | ■ |
| openai | OpenAI | 3 | 2 | ■ | ■ |
| huggingfaceDedicated | Hugging Face - Dedicated | 1 | 3 | ■ | ■ |
| azureOpenAI | Azure OpenAI | 3 | 2 | ■ | ■ |
| bedrock | Amazon Bedrock | 2 | 1 | ■ | ■ |
| jinaAI | Jina AI | 5 | 0 | ■ | ■ |
| voyageAI | Voyage AI | 7 | 1 | ■ | ■ |
| upstageAI | Upstage | 1 | 0 | ■ | ■ |
| huggingface | Hugging Face - Serverless| 6 | 0 | ■ | ■ |
| nvidia | Nvidia | 1 | 0 | | |
| mistral | Mistral AI | 1 | 0 | ■ | ■ |
+----------------------+--------------------------+--------+------------+---------+----------+|
Supported embedding providers are subject to change and may be different from the sample result. |
Use the astra db describe-embedding-provider command to get information about a specific embedding provider integration:
astra db describe-embedding-provider DATABASE_ID -ep PROVIDER_NAMEThe PROVIDER_NAME is the name listed in the Key column in the output of the astra db list-embedding-providers command.
Result
+-------------------+---------------------------------------------------------------------------------------------+
| Attribute | Value |
+-------------------+---------------------------------------------------------------------------------------------+
| Key | openai |
| DisplayName | OpenAI |
| Parameters | [0] organizationId (STRING) |
| | [1] projectId (STRING) |
| Models: | |
| Name | text-embedding-3-small |
| Parameters | [0] vectorDimension (number) , defaultValue=1536 |
| Name | text-embedding-3-large |
| Parameters | [0] vectorDimension (number) , defaultValue=3072 |
| Name | text-embedding-ada-002 |
| Vector Dimension | 1536 |
| Header Auth: | |
| Tokens | [0] forwarded=Authorization, accepted=x-embedding-api-key |
| Shar.Secret Auth: | |
| Tokens | [0] forwarded=Authorization, accepted=providerKey |
| Supported Auth: | |
| Authentication | [0] NONE: [] |
| | [1] SHARED_SECRET: [EmbeddingProvider.Token(forwarded=Authorization, accepted=providerKey)] |
| | [2] HEADER: [EmbeddingProvider.Token(forwarded=Authorization, accepted=x-embedding-api-key)]|
+-------------------+---------------------------------------------------------------------------------------------+
[OK] Database '58747660-464b-4085-bef2-c3f3e5401e3d' is ready.|
Supported embedding providers are subject to change and may be different from the sample result. |
db list-embedding-providers options
Expand to see all db list-embedding-providers options
NAME
astra db list-embedding-providers - Display the list of embedding
providers in an database
SYNOPSIS
astra db list-embedding-providers
[ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --no-color ] [ {-o | --output} <FORMAT> ]
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb describe-embedding-provider options
Expand to see all db describe-embedding-provider options
NAME
astra db describe-embedding-provider - Describe an existing embedding
provider
SYNOPSIS
astra db describe-embedding-provider
[ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
{-ep | --embedding-provider} <EMBEDDING_PROVIDER>
[ --no-color ] [ {-o | --output} <FORMAT> ]
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-ep <EMBEDDING_PROVIDER>, --embedding-provider <EMBEDDING_PROVIDER>
Key of the embedding provider
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierGet database details
Use the astra db list command to get a list of all the databases in your organization:
astra db listResult
+---------------------+--------------------------------------+-----------+-------+---+-----------+
| Name | id | Regions | Cloud | V | Status |
+---------------------+--------------------------------------+-----------+-------+---+-----------+
| my_serverless_db | 51d23de8-9fd9-487c-9c46-c8e1abdb251b | us-east1 | gcp | | ACTIVE |
| my_vector_db | 6fabb532-a3ac-4780-a1bc-d984531aed76 | us-east1 | gcp | ■ | ACTIVE |
+---------------------+--------------------------------------+-----------+-------+---+-----------+Use the astra db get or astra db describe command to get information about a specific database:
astra db get DATABASE_IDastra db describe DATABASE_IDResult
+------------------+-----------------------------------------+
| Attribute | Value |
+------------------+-----------------------------------------+
| Name | my_serverless_db |
| id | 96b1b6e3-5288-4cef-8a41-d4f1d36bbfca |
| Cloud | GCP |
| Regions | us-east1 |
| Status | ACTIVE |
| Vector | Disabled |
| Default Keyspace | default_keyspace |
| Creation Time | 2025-01-22T21:21:14Z |
| Keyspaces | [0] default_keyspace |
| Regions | [0] us-east1 |
+------------------+-----------------------------------------+Use the astra db status command to get the status of a specific database:
astra db status DATABASE_IDResult
[OK] Database '96b1b6e3-5288-4cef-8a41-d4f1d36bbfca' has status 'ACTIVE'db list options
Expand to see all db list options
NAME
astra db list - Display the list of Databases in an organization
SYNOPSIS
astra db list [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --no-color ] [ {-o | --output} <FORMAT> ]
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [ --vector ]
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--vector
Create a database with vector search enabledUse the --vector option to list only Serverless (Vector) databases:
astra db list --vectorResult
+---------------------+--------------------------------------+-----------+-------+---+-----------+
| Name | id | Regions | Cloud | V | Status |
+---------------------+--------------------------------------+-----------+-------+---+-----------+
| my_vector_db | ebae8d5a-4848-44c9-8485-87e413b60549 | us-east1 | gcp | ■ | ACTIVE |
+---------------------+--------------------------------------+-----------+-------+---+-----------+db get options
Expand to see all `db get options
NAME
astra db get - Show details of a database
SYNOPSIS
astra db get [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ {-k | --key} <Key> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-k <Key>, --key <Key>
Show value for a property among: 'id', 'status', 'cloud',
'keyspace', 'keyspaces', 'region', 'regions'
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb describe options
Expand to see all db describe options
NAME
astra db describe - Show details of a database
SYNOPSIS
astra db describe [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ {-k | --key} <Key> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-k <Key>, --key <Key>
Show value for a property among: 'id', 'status', 'cloud',
'keyspace', 'keyspaces', 'region', 'regions'
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb status options
Expand to see all db status options
NAME
astra db status - Show status of a database
SYNOPSIS
astra db status [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --no-color ] [ {-o | --output} <FORMAT> ]
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierGet a list of available Astra DB regions
Use the astra db list-regions-serverless command to get a list of available cloud provider regions that support Serverless (Non-Vector) databases:
astra db list-regions-serverlessResult
+-----------------+-------------------------+---------------------------------------+
| Cloud Provider | Region | Full Name |
+-----------------+-------------------------+---------------------------------------+
| aws | ap-east-1 | Asia Pacific (Hong Kong) |
| aws | ap-south-1 | Asia Pacific (Mumbai) |
| aws | ap-southeast-1 | Asia Pacific (Singapore) |
| aws | ap-southeast-2 | Asia Pacific (Sydney) |
| aws | ca-central-1 | Canada (Central) |
| aws | ca-west-1 | Canada West (Calgary) |
| aws | eu-central-1 | Europe (Frankfurt) |
| aws | eu-west-1 | Europe (Ireland) |
| aws | eu-west-2 | Europe (London) |
| aws | me-central-1 | Middle East (UAE) |
| aws | sa-east-1 | South America (Sao Paulo) |
| aws | us-east-1 | US East (N. Virginia) |
| aws | us-east-2 | US East (Ohio) |
| aws | us-west-2 | US West (Oregon) |
| azure | australiaeast | Australia East |
| azure | brazilsouth | Brazil South (Sao Paulo) |
| azure | canadacentral | Canada Central (Toronto) |
| azure | centralindia | Central India (Pune) |
| azure | centralus | (US) Central US |
| azure | eastus | US East |
| azure | eastus2 | US East 2 (Virginia) |
| azure | northeurope | Northern Europe (Ireland) |
| azure | westeurope | West Europe |
| azure | westus2 | US West (Washington) |
| azure | westus3 | US West 3 |
| gcp | asia-northeast1 | Asia Northeast1 (Tokyo, Japan) |
| gcp | asia-northeast2 | Osaka, Japan, APAC |
| gcp | asia-south1 | Mumbai, India |
| gcp | australia-southeast1 | Sydney, Australia, APAC |
| gcp | europe-west1 | St. Ghislain, Belgium |
| gcp | europe-west2 | West Europe2 (London, England, UK) |
| gcp | europe-west3 | West Europe3 (Frankfurt, Germany) |
| gcp | europe-west4 | West Europe4 (Eemshaven, Netherlands) |
| gcp | northamerica-northeast1 | Montreal, Quebec |
| gcp | northamerica-northeast2 | Toronto, Ontario |
| gcp | us-central1 | Council Bluffs, Iowa |
| gcp (free-tier) | us-east1 | Moncks Corner, South Carolina |
| gcp | us-east4 | Ashburn, Virginia |
| gcp | us-west1 | The Dalles, Oregon |
| gcp | us-west4 | US West (Las Vegas, USA) |
+-----------------+-------------------------+---------------------------------------+|
Supported regions are subject to change and may be different from the sample result. |
Use the astra db list-regions-vector command to get a list of available cloud provider regions that support Serverless (Vector) databases:
astra db list-regions-vectorResult
+-----------------+-------------------------+------------------------------------+
| Cloud Provider | Region | Full Name |
+-----------------+-------------------------+------------------------------------+
| aws | ap-south-1 | Asia Pacific (Mumbai) |
| aws | ap-southeast-2 | Asia Pacific (Sydney) |
| aws | eu-west-1 | Europe (Ireland) |
| aws | us-east-1 | US East (N. Virginia) |
| aws | us-east-2 | US East (Ohio) |
| azure | australiaeast | Australia East |
| azure | centralindia | Central India (Pune) |
| azure | westeurope | West Europe |
| azure | westus3 | US West 3 |
| gcp | europe-west2 | West Europe2 (London, England, UK) |
| gcp | northamerica-northeast1 | Montreal, Quebec |
| gcp (free-tier) | us-east1 | Moncks Corner, South Carolina |
| gcp | us-east4 | Ashburn, Virginia |
+-----------------+-------------------------+------------------------------------+|
Supported regions are subject to change and may be different from the sample result. |
Use the astra db list-regions-classic command to get a list of available cloud provider regions that support Classic databases:
astra db list-regions-classicResult
+-----------------+-------------------------+-------------------------------+
| Cloud Provider | Region | Full Name |
+-----------------+-------------------------+-------------------------------+
| aws | af-south-1 | Africa (Cape Town) |
| aws | ap-east-1 | Hong Kong |
| aws | ap-south-1 | Asia Pacific (Mumbai) |
| aws | ap-southeast-1 | Asia Pacific (Singapore) |
| aws | ap-southeast-2 | Asia Pacific (Sydney) |
| aws | ca-central-1 | Canada (Central) |
| aws | ca-west-1 | Canada West (Calgary) |
| aws | eu-central-1 | Europe (Frankfurt) |
| aws | eu-west-1 | EU West 1 (Ireland) |
| aws | eu-west-2 | Europe (London) |
| aws | me-central-1 | Middle East (UAE) |
| aws | sa-east-1 | Sao Paulo |
| aws | us-east-1 | US East (N. Virginia) |
| aws | us-east-2 | US East (Ohio) |
| aws | us-west-2 | US West (Oregon) |
| azure | australiaeast | Australia East |
| azure | brazilsouth | Brazil South |
| azure | canadacentral | Canada Central (Toronto) |
| azure | centralindia | Central India |
| azure | centralus | (US) Central US |
| azure | eastus2 | East US 2 (Virginia) |
| azure | northeurope | North Europe |
| azure | southcentralus | South Central US |
| azure | westeurope | West Europe |
| azure | westus2 | West US 2 (Washington) |
| azure | westus3 | West US 3 |
| gcp | asia-northeast2 | Osaka, Japan, APAC |
| gcp | asia-south1 | Mumbai, India |
| gcp | europe-west1 | St. Ghislain, Belgium |
| gcp | northamerica-northeast1 | NA Northeast 1 (Montreal) |
| gcp | southamerica-east1 | Osasco, Sao Paulo, Brazil |
| gcp | us-central1 | US Central (Iowa) |
| gcp (free-tier) | us-east1 | US East (South Carolina) |
| gcp | us-east4 | US East 4 (Virginia) |
| gcp | us-west1 | The Dalles, Oregon |
+-----------------+-------------------------+-------------------------------+-+|
Supported regions are subject to change and may be different from the sample result. |
db list-regions-serverless options
Expand to see all db list-regions-serverless options
NAME
astra db list-regions-serverless - Show available regions (serverless).
SYNOPSIS
astra db list-regions-serverless [ {-c | --cloud} <CLOUD> ]
[ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ {-f | --filter} <filter> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ]
OPTIONS
-c <CLOUD>, --cloud <CLOUD>
Filter on Cloud provider
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-f <filter>, --filter <filter>
Filter on names
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in consoledb list-regions-vector options
Expand to see all db list-regions-vector options
NAME
astra db list-regions-vector - Show available regions (vector).
SYNOPSIS
astra db list-regions-vector [ {-c | --cloud} <CLOUD> ]
[ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ {-f | --filter} <filter> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ]
OPTIONS
-c <CLOUD>, --cloud <CLOUD>
Filter on Cloud provider
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-f <filter>, --filter <filter>
Filter on names
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in consoledb list-regions-classic options
Expand to see all db list-regions-classic options
NAME
astra db list-regions-classic - Show available regions (classic).
SYNOPSIS
astra db list-regions-classic [ {-c | --cloud} <CLOUD> ]
[ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ {-f | --filter} <filter> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ]
OPTIONS
-c <CLOUD>, --cloud <CLOUD>
Filter on Cloud provider
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-f <filter>, --filter <filter>
Filter on names
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in consoledb list-clouds options
Expand to see all db list-clouds options
NAME
astra db list-clouds - Show available clouds
SYNOPSIS
astra db list-clouds [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --no-color ] [ {-o | --output} <FORMAT> ]
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ]
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in consoleConfigure multiple regions
You can configure a database to replicate data across multiple regions. Some benefits of multi-region databases include better data locality and higher availability for multi-region application architectures. For more information, see Configure multiple regions for a database.
|
Multi-region databases are a premium feature. Each region added to a database increases the database’s costs. This includes a one-time data replication fee for the new region, and charges for replicating data to all database regions. For more information, see Subscriptions and billing. |
Use the astra db create-region command to add a region to a database:
astra db create-region DATABASE_ID -r REGIONReplace REGION with the region you want to add to your database.
The following restrictions apply:
-
You can add only one region at a time.
-
You can’t select a region that the database already uses.
-
You must select a region in the same cloud provider as the database’s other regions. Multi-region databases can’t span multiple cloud providers.
-
For Serverless (Vector) databases, you must select a region that supports that database type. For more information, see Astra DB Serverless database regions and maintenance schedules.
|
The database enters Maintenance status while provisioning and replicating data to the new region. While in Maintenance status, you can’t add or remove regions, truncate tables, or delete keyspaces, tables, or collections. Maintenance status doesn’t impact reads and writes. |
Use the astra db list-regions command to list the regions where a database is deployed:
astra db list-regions DATABASE_IDResult
+----------------+---------------------+----------------+----------------+
| Cloud Provider | Region | Tier | Status |
+----------------+---------------------+----------------+----------------+
| aws | us-east-2 | serverless | |
| aws | us-east-1 (default) | serverless | |
+----------------+---------------------+----------------+----------------+Use the astra db delete-region command to remove a region from a database:
astra db delete-region DATABASE_ID -r REGIONResult
[INFO] Region 'us-west1' is deleting.
[OK] Region us-west1 has been deleted|
The database enters Maintenance status while deleting the region. While in Maintenance status, you can’t add or remove regions, truncate tables, or delete keyspaces, tables, or collections. Maintenance status doesn’t impact reads and writes. |
|
You can’t remove the primary (default) region, which is the first region selected when you created the database. When you remove a region, any connections to the deleted region are also removed. However, to avoid data loss, all data is replicated before the region is deleted. |
db create-region options
Expand to see all db create-region options
NAME
astra db create-region - Expand database to a new region
SYNOPSIS
astra db create-region [ --async ] [ {-c | --cloud} <CLOUD> ]
[ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --if-not-exist ] [ --no-color ] [ {-o | --output} <FORMAT> ]
{-r | --region} <REGION> [ {-t | --tier} <CLOUD> ]
[ --timeout <timeout> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [ --wait ] [--] <DB>
OPTIONS
--async
Will wait until the database become ACTIVE
-c <CLOUD>, --cloud <CLOUD>
Name of the cloud provider
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--if-not-exist
will create a new DB only if none with same name
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
-r <REGION>, --region <REGION>
Name of the region to create
-t <CLOUD>, --tier <CLOUD>
Name of the tiers
--timeout <timeout>
Max wait time in seconds, default+1800, 0 = no timeout.
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--wait
Will wait until the database become ACTIVE
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb list-regions options
Expand to see all db list-regions options
NAME
astra db list-regions - List regions for a database
SYNOPSIS
astra db list-regions [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --no-color ] [ {-o | --output} <FORMAT> ]
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb delete-region options
Expand to see all db delete-region options
NAME
astra db delete-region - Delete a region from a database
SYNOPSIS
astra db delete-region [ --async ]
[ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --no-color ] [ {-o | --output} <FORMAT> ]
{-r | --region} <REGION> [ --timeout <timeout> ]
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [ --wait ] [--]
<DB>
OPTIONS
--async
Will wait until the database become ACTIVE
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
-r <REGION>, --region <REGION>
Name of the region to create
--timeout <timeout>
Max wait time in seconds, default+1800, 0 = no timeout.
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--wait
Will wait until the database become ACTIVE
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierResume a hibernated database
Use the astra db resume command to resume a hibernated database:
astra db resume DATABASE_IDResuming the database may take a few minutes.
By default, the command runs synchronously and doesn’t return the command prompt until the database reaches Active or Error status.
To run the command asynchronously, add the --async option.
db resume options
Expand to see all db resume options
NAME
astra db resume - Resume a db if needed
SYNOPSIS
astra db resume [ --async ] [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --no-color ] [ {-o | --output} <FORMAT> ]
[ --timeout <timeout> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [ --wait ] [--] <DB>
OPTIONS
--async
Will not wait for the resource to become available
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--timeout <timeout>
Provide a limit to the wait period in seconds, default is 180s.
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--wait
Will wait until the database become ACTIVE
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierTerminate a database
|
Terminating a database permanently deletes all of its data, including automatic backups. You can’t undo this action. |
Use the astra db delete command to terminate a database:
astra db delete DATABASE_IDResult
[INFO] Deleting Database '26054aa9-eb37-4d88-b343-7c934cd1d7bc'
[OK] Database 26054aa9-eb37-4d88-b343-7c934cd1d7bc has been deletedThe database enters Terminating status while deletion occurs.
By default, the command runs synchronously and doesn’t return the command prompt until the database reaches Terminated or Error status.
To run the command asynchronously, add the --async option.
db delete options
Expand to see all db delete options
NAME
astra db delete - Delete an existing database
SYNOPSIS
astra db delete [ --async ] [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --no-color ] [ {-o | --output} <FORMAT> ]
[ --timeout <timeout> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [ --wait ] [--] <DB>
OPTIONS
--async
Will not wait for the resource to become available
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--timeout <timeout>
Provide a limit to the wait period in seconds, default is 500s.
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--wait
Will wait until the database become ACTIVE
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierGet database API endpoints
Use the get-endpoint-swagger command to get the Swagger UI endpoint for a database:
astra db get-endpoint-swagger DATABASE_IDResult
https://26054aa9-eb37-4d88-b343-7c934cd1d7bc-us-east-1.apps.astra.datastax.com/api/rest/swagger-ui/Use the get-endpoint-api command to get the JSON API endpoint for a Serverless (Vector) database:
astra db get-endpoint-api DATABASE_IDResult
https://26054aa9-eb37-4d88-b343-7c934cd1d7bc-us-east-1.apps.astra.datastax.com/api/restUse the get-endpoint-playground command to get the GraphQL playground endpoint for a non-vector database:
astra db get-endpoint-playground DATABASE_IDResult
https://26054aa9-eb37-4d88-b343-7c934cd1d7bc-us-east-1.apps.astra.datastax.com/api/playgrounddb get-endpoint-swagger options
Expand to see all db get-endpoint-swagger options
NAME
astra db get-endpoint-swagger - Open the swagger user interface
SYNOPSIS
astra db get-endpoint-swagger [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --no-color ] [ {-o | --output} <FORMAT> ]
[ {-r | --region} <DB_REGION> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
-r <DB_REGION>, --region <DB_REGION>
Cloud provider region
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb get-endpoint-api options
Expand to see all db get-endpoint-api options
NAME
astra db get-endpoint-api - Open the json api endpoint
SYNOPSIS
astra db get-endpoint-api [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --no-color ] [ {-o | --output} <FORMAT> ]
[ {-r | --region} <DB_REGION> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
-r <DB_REGION>, --region <DB_REGION>
Cloud provider region
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb get-endpoint-playground options
Expand to see all db get-endpoint-playground options
NAME
astra db get-endpoint-playground - Expand database to a new region
SYNOPSIS
astra db get-endpoint-playground
[ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --no-color ] [ {-o | --output} <FORMAT> ]
[ {-r | --region} <DB_REGION> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
-r <DB_REGION>, --region <DB_REGION>
Cloud provider region
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierUse the CQL shell (cqlsh)
The CQL shell (cqlsh) is an interface that you can use to issue Cassandra Query Language (CQL) commands to your database.
The Astra CLI provides built-in CQL shell support by downloading, installing, configuring, and wapping the cqlsh utility.
This can act as a convenient alternative to installing and configuring a standalone CQL shell.
To use cqlsh commands, you must have a supported version of Python installed on your system.
The underlying cqlsh utility requires Python 2.7 (with TLS support) or Python 3.6—3.11.
Python versions 3.12 and later are not supported.
For more details, see this Support article
Use the astra db cqlsh command to start the CQL shell in interactive mode:
astra db cqlsh DATABASE_IDResult
[INFO] Downloading Cqlshell, please wait...
[INFO] Installing archive, please wait...
[INFO] Cqlsh is starting, please wait for connection establishment...
Connected to cndb at 127.0.0.1:9042.
[cqlsh 6.8.0 | Cassandra 4.0.0.6816 | CQL spec 3.4.5 | Native protocol v4]
Use HELP for help.
token@cqlsh>Type exit or quit; and press Return to exit the CQL shell.
The first time you use the astra db cqlsh command, the Astra CLI downloads and installs the cqlsh utility to the Astra CLI installation directory (~/.astra/cqlsh-astra).
The Astra CLI also downloads the Secure Connect Bundle (SCB) for each database you connect to and stores the SCB zip files in the ~/.astra/scb directory.
|
If the Astra CLI reports Result |
db cqlsh options
Expand to see all db cqlsh options
NAME
astra db cqlsh - Start Cqlsh
SYNOPSIS
astra db cqlsh [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ]
[ --connect-timeout <TIMEOUT> ] [ --debug ]
[ {-e | --execute} <STATEMENT> ] [ --encoding <ENCODING> ]
[ --env <Environment> ] [ {-f | --file} <FILE> ]
[ {-k | --keyspace} <KEYSPACE> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] [ --request-timeout <TIMEOUT> ]
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [ --version ]
[--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--connect-timeout <TIMEOUT>
Connection timeout in seconds (default is 10
--debug
Show additional debugging information.
-e <STATEMENT>, --execute <STATEMENT>
Execute the statement and quit.
--encoding <ENCODING>
Output encoding. Default encoding: utf8.
--env <Environment>
Astra Environment to use
-f <FILE>, --file <FILE>
Execute commands from a CQL file, then exit.
-k <KEYSPACE>, --keyspace <KEYSPACE>
Authenticate to the given keyspace.
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--request-timeout <TIMEOUT>
Request timeout in seconds (default is 20
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--version
Display information of cqlsh.
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierUse the -k / --keyspace option to connect directly to a specific keyspace:
astra db cqlsh DATABASE_ID -k KEYSPACE_NAMEResult
[INFO] Cqlsh is starting, please wait for connection establishment...
Connected to cndb at 127.0.0.1:9042.
[cqlsh 6.8.0 | Cassandra 4.0.0.6816 | CQL spec 3.4.5 | Native protocol v4]
Use HELP for help.
token@cqlsh:keyspace2>Use the -e / --execute option to execute a CQL statement:
astra db cqlsh DATABASE_ID -e "describe keyspaces;"Result
[INFO] Cqlsh is starting, please wait for connection establishment...
system_auth data_endpoint_auth system_traces
datastax_sla default_keyspace system_virtual_schema
system_schema system system_viewsUse the -f / --file option to execute a CQL file:
astra db cqlsh DATABASE_ID -f sample.cqlExample CQL file
sample.cql
-- Use a specific keyspace
USE keyspace1;
-- Create a table
CREATE TABLE IF NOT EXISTS users (
id UUID PRIMARY KEY,
name TEXT,
email TEXT
);
-- Insert some data
INSERT INTO users (id, name, email) VALUES (uuid(), 'Alice', 'alice@example.com');
INSERT INTO users (id, name, email) VALUES (uuid(), 'Bob', 'bob@example.com');
-- Query the data
SELECT * FROM users;Result
[INFO] Cqlsh is starting, please wait for connection establishment...
id | email | name
--------------------------------------+-------------------+-------
62a32f14-5432-4a28-add7-761d3626373e | bob@example.com | Bob
0a489e53-0eed-4385-81a6-081143c228f1 | alice@example.com | Alice
(2 rows)|
You can also execute a CQL file using the Result |
Use DataStax Bulk Loader (DSBulk)
The DataStax Bulk Loader (DSBulk) lets you load, unload, and count data in your database tables.
The Astra CLI provides built-in DSBulk support by downloading, installing, configuring, and wapping the dsbulk utility.
The Astra CLI exposes DSBulk functionality through the astra db load, astra db unload, and astra db count commands.
Use the astra db load command to load data from a file into a database table:
astra db load DATABASE_ID \
-k KEYSPACE_NAME \
-t TABLE_NAME \
-url FILE_LOCATIONResult
[INFO] Downloading Dsbulk, please wait...
[INFO] Installing archive, please wait...
[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk load -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO -delim , -url cities.csv -header true -encoding UTF-8 -skipRecords 0 -maxErrors 100
[INFO] DSBulk is starting please wait ...
Username and password provided but auth provider not specified, inferring PlainTextAuthProvider
A cloud secure connect bundle was provided: ignoring all explicit contact points.
A cloud secure connect bundle was provided and selected operation performs writes: changing default consistency level to LOCAL_QUORUM.
Operation directory: /Users/USERNAME/logs/LOAD_20250123-020734-995267
Setting executor.maxPerSecond not set when connecting to DataStax Astra: applying a limit of 27,000 ops/second based on the number of coordinators (9).
If your Astra database has higher limits, please define executor.maxPerSecond explicitly.
total | failed | rows/s | p50ms | p99ms | p999ms | batches
148,266 | 0 | 19,588 | 240.82 | 771.75 | 964.69 | 30.72
Operation LOAD_20250123-020734-995267 completed successfully in 7 seconds.
Checkpoints for the current operation were written to checkpoint.csv.
To resume the current operation, re-run it with the same settings, and add the following command line flag:
--dsbulk.log.checkpoint.file=/Users/USERNAME/logs/LOAD_20250123-020734-995267/checkpoint.csv|
You can use the Result |
Use the astra db unload command to unload database table rows into a file:
astra db unload DATABASE_ID \
-k KEYSPACE_NAME \
-t TABLE_NAME \
-url FILE_LOCATIONResult
[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk unload -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO -delim , -url unloaded_data -header true -encoding UTF-8 -skipRecords 0 -maxErrors 100
[INFO] DSBulk is starting please wait ...
Username and password provided but auth provider not specified, inferring PlainTextAuthProvider
A cloud secure connect bundle was provided: ignoring all explicit contact points.
Operation directory: /Users/USERNAME/logs/UNLOAD_20250123-021231-557959
total | failed | rows/s | p50ms | p99ms | p999ms
134,574 | 0 | 29,767 | 281.25 | 591.40 | 591.40
Operation UNLOAD_20250123-021231-557959 completed successfully in 4 seconds.
Checkpoints for the current operation were written to checkpoint.csv.
To resume the current operation, re-run it with the same settings, and add the following command line flag:
--dsbulk.log.checkpoint.file=/Users/USERNAME/logs/UNLOAD_20250123-021231-557959/checkpoint.csvUse the astra db count command to get information about loaded data:
astra db count DATABASE_ID \
-k KEYSPACE_NAME \
-t TABLE_NAMEResult
[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk count -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO
[INFO] DSBulk is starting please wait ...
Username and password provided but auth provider not specified, inferring PlainTextAuthProvider
A cloud secure connect bundle was provided: ignoring all explicit contact points.
Operation directory: /Users/USERNAME/logs/COUNT_20250123-021120-127216
total | failed | rows/s | p50ms | p99ms | p999ms
134,574 | 0 | 65,674 | 213.18 | 329.25 | 329.25
Operation COUNT_20250123-021120-127216 completed successfully in 1 second.
Checkpoints for the current operation were written to checkpoint.csv.
To resume the current operation, re-run it with the same settings, and add the following command line flag:
--dsbulk.log.checkpoint.file=/Users/USERNAME/logs/COUNT_20250123-021120-127216/checkpoint.csv
134574|
The first time you use one of the |
db load options
Expand to see all db load options
NAME
astra db load - Load data leveraging DSBulk
SYNOPSIS
astra db load [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ -delim <delim> ]
[ -dryRun ] [ --dsbulk-config <DSBULK_CONF_FILE> ]
[ -encoding <ENCODING> ] [ --env <Environment> ]
[ -header <header> ] [ {-k | --keyspace} <KEYSPACE> ]
[ -logDir <log directory> ]
[ {-m | --schema.mapping} <mapping> ]
[ -maxConcurrentQueries <maxConcurrentQueries> ]
[ -maxErrors <maxErrors> ] [ --no-color ]
[ {-o | --output} <FORMAT> ]
[ {-query | --schema.query} <QUERY> ]
[ --schema.allowMissingFields <allowMissingFields> ]
[ -skipRecords <skipRecords> ] [ {-t | --table} <TABLE> ]
[ --token <AUTH_TOKEN> ] -url <url> [ {-v | --verbose} ] [--]
<DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
-delim <delim>
Character(s) use as field delimiter.
-dryRun
Enable or disable dry-run mode.
--dsbulk-config <DSBULK_CONF_FILE>
Not all options offered by the loader DSBulk are exposed in this
CLI
-encoding <ENCODING>
The file name format to use when writing. This setting is ignored
when reading and for non-file URLs.
--env <Environment>
Astra Environment to use
-header <header>
Read, Write Header in input file
-k <KEYSPACE>, --keyspace <KEYSPACE>
Keyspace used for loading or unloading data.
-logDir <log directory>
Optional filter
-m <mapping>, --schema.mapping <mapping>
Field-to-column mapping to use.
-maxConcurrentQueries <maxConcurrentQueries>
The maximum number of concurrent queries that should be carried in
parallel.
-maxErrors <maxErrors>
Maximum number of errors before aborting the operation.
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
-query <QUERY>, --schema.query <QUERY>
Optional to unload or count
--schema.allowMissingFields <allowMissingFields>
Ease the mapping
-skipRecords <skipRecords>
Lines to skip before readind
-t <TABLE>, --table <TABLE>
Table used for loading or unloading data. Table names should not be
quoted and are case-sensitive.
--token <AUTH_TOKEN>
Key to use authenticate each call.
-url <url>
File location to load data
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb unload options
Expand to see all db unload options
NAME
astra db unload - Unload data leveraging DSBulk
SYNOPSIS
astra db unload [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ -delim <delim> ]
[ --dsbulk-config <DSBULK_CONF_FILE> ] [ -encoding <ENCODING> ]
[ --env <Environment> ] [ -header <header> ]
[ {-k | --keyspace} <KEYSPACE> ] [ -logDir <log directory> ]
[ {-m | --schema.mapping} <mapping> ]
[ -maxConcurrentQueries <maxConcurrentQueries> ]
[ -maxErrors <maxErrors> ] [ --no-color ]
[ {-o | --output} <FORMAT> ]
[ {-query | --schema.query} <QUERY> ]
[ -skipRecords <skipRecords> ] [ {-t | --table} <TABLE> ]
[ --token <AUTH_TOKEN> ] [ -url <url> ] [ {-v | --verbose} ]
[--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
-delim <delim>
The character(s) to use as field delimiter. Field delimiters
containing more than one character are accepted.
--dsbulk-config <DSBULK_CONF_FILE>
Not all options offered by the loader DSBulk are exposed in this
CLI
-encoding <ENCODING>
The file name format to use when writing. This setting is ignored
when reading and for non-file URLs.
--env <Environment>
Astra Environment to use
-header <header>
Enable or disable whether the files to read or write begin with a
header line.
-k <KEYSPACE>, --keyspace <KEYSPACE>
Keyspace used for loading or unloading data.
-logDir <log directory>
Optional filter
-m <mapping>, --schema.mapping <mapping>
The field-to-column mapping to use, that applies to both loading
and unloading; ignored when counting.
-maxConcurrentQueries <maxConcurrentQueries>
The maximum number of concurrent queries that should be carried in
parallel.
-maxErrors <maxErrors>
The maximum number of errors to tolerate before aborting the entire
operation.
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
-query <QUERY>, --schema.query <QUERY>
Optional to unload or count
-skipRecords <skipRecords>
The number of records to skip from each input file before the
parser can begin to execute. Note that if the file contains a
header line, that line is not counted as a valid record. This
setting is ignored when writing.
-t <TABLE>, --table <TABLE>
Table used for loading or unloading data. Table names should not be
quoted and are case-sensitive.
--token <AUTH_TOKEN>
Key to use authenticate each call.
-url <url>
The URL or path of the resource(s) to read from or write to.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb count options
Expand to see all db count options
NAME
astra db count - Count items for a table, a query
SYNOPSIS
astra db count [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ]
[ --dsbulk-config <DSBULK_CONF_FILE> ] [ -encoding <ENCODING> ]
[ --env <Environment> ] [ {-k | --keyspace} <KEYSPACE> ]
[ -logDir <log directory> ]
[ -maxConcurrentQueries <maxConcurrentQueries> ] [ --no-color ]
[ {-o | --output} <FORMAT> ]
[ {-query | --schema.query} <QUERY> ]
[ {-t | --table} <TABLE> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--dsbulk-config <DSBULK_CONF_FILE>
Not all options offered by the loader DSBulk are exposed in this
CLI
-encoding <ENCODING>
The file name format to use when writing. This setting is ignored
when reading and for non-file URLs.
--env <Environment>
Astra Environment to use
-k <KEYSPACE>, --keyspace <KEYSPACE>
Keyspace used for loading or unloading data.
-logDir <log directory>
Optional filter
-maxConcurrentQueries <maxConcurrentQueries>
The maximum number of concurrent queries that should be carried in
parallel.
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
-query <QUERY>, --schema.query <QUERY>
Optional to unload or count
-t <TABLE>, --table <TABLE>
Table used for loading or unloading data. Table names should not be
quoted and are case-sensitive.
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierEnd-to-end example
The following end-to-end example shows how to use the Astra CLI’s built-in DSBulk support to load data into a database, get information about the data, and unload the data into CSV files:
-
Create an Astra DB Serverless (Non-Vector) database:
astra db create dsbulk_demo_db -k dsbulk_demo_keyspaceResult
[INFO] Database 'dsbulk_demo_db' does not exist. Creating database 'dsbulk_demo_db' with keyspace 'dsbulk_demo_keyspace' [INFO] Database 'dsbulk_demo_db' and keyspace 'dsbulk_demo_keyspace' are being created. [INFO] Database 'dsbulk_demo_db' has status 'PENDING' waiting to be 'ACTIVE' ... [INFO] Database 'dsbulk_demo_db' has status 'ACTIVE' (took 471460 millis) [OK] Database 'dsbulk_demo_db' is ready. -
Download the cities.csv file and move it to the directory where you run Astra CLI commands.
The
cities.csvdataset contains information about cities around the world:cities.csvid,name,state_id,state_code,state_name,country_id,country_code,country_name,latitude,longitude,wikiDataId 52,Ashkāsham,3901,BDS,Badakhshan,1,AF,Afghanistan,36.68333000,71.53333000,Q4805192 68,Fayzabad,3901,BDS,Badakhshan,1,AF,Afghanistan,37.11664000,70.58002000,Q156558 ... -
Create a table in your database to store your data.
-
Start the CQL shell in interactive mode:
astra db cqlsh dsbulk_demo_db -k dsbulk_demo_keyspaceResult
[INFO] Cqlsh is starting, please wait for connection establishment... Connected to cndb at 127.0.0.1:9042. [cqlsh 6.8.0 | Cassandra 4.0.0.6816 | CQL spec 3.4.5 | Native protocol v4] Use HELP for help. token@cqlsh:dsbulk_demo_keyspace> -
Copy and paste the following CQL command into the
cqlshprompt and press Return:CREATE TABLE cities_by_country ( country_name text, name text, id int, state_id text, state_code text, state_name text, country_id text, country_code text, latitude double, longitude double, wikiDataId text, PRIMARY KEY ((country_name), name) );This command creates a table named
cities_by_countrywith the appropriate schema for thecities.csvdataset. -
Type
exitorquit;and press Return to exit the CQL shell.
-
-
Load the data from the
cities.csvfile into thecities_by_countrytable that you just created in your database:astra db load dsbulk_demo_db \ -k dsbulk_demo_keyspace \ -t cities_by_country \ -url cities.csvResult
[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk load -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO -delim , -url cities.csv -header true -encoding UTF-8 -skipRecords 0 -maxErrors 100 [INFO] DSBulk is starting please wait ... Username and password provided but auth provider not specified, inferring PlainTextAuthProvider A cloud secure connect bundle was provided: ignoring all explicit contact points. A cloud secure connect bundle was provided and selected operation performs writes: changing default consistency level to LOCAL_QUORUM. Operation directory: /Users/USERNAME/logs/LOAD_20250123-020734-995267 Setting executor.maxPerSecond not set when connecting to DataStax Astra: applying a limit of 27,000 ops/second based on the number of coordinators (9). If your Astra database has higher limits, please define executor.maxPerSecond explicitly. total | failed | rows/s | p50ms | p99ms | p999ms | batches 148,266 | 0 | 19,588 | 240.82 | 771.75 | 964.69 | 30.72 Operation LOAD_20250123-020734-995267 completed successfully in 7 seconds. Checkpoints for the current operation were written to checkpoint.csv. To resume the current operation, re-run it with the same settings, and add the following command line flag: --dsbulk.log.checkpoint.file=/Users/USERNAME/logs/LOAD_20250123-020734-995267/checkpoint.csv -
Confirm that the data loaded successfully:
astra db cqlsh dsbulk_demo_db -e \ "select * from dsbulk_demo_keyspace.cities_by_country LIMIT 20;"Result
[INFO] Cqlsh is starting, please wait for connection establishment... country_name | name | country_code | country_id | id | latitude | longitude | state_code | state_id | state_name | wikidataid --------------+---------------------+--------------+------------+------+----------+-----------+------------+----------+---------------------+------------ Bangladesh | Azimpur | BD | 19 | 8454 | 23.7298 | 90.3854 | 13 | 771 | Dhaka District | null Bangladesh | Badarganj | BD | 19 | 8455 | 25.67419 | 89.05377 | 55 | 759 | Rangpur District | null Bangladesh | Bagerhat | BD | 19 | 8456 | 22.4 | 89.75 | 27 | 811 | Khulna District | null Bangladesh | Bandarban | BD | 19 | 8457 | 22 | 92.33333 | B | 803 | Chittagong Division | null Bangladesh | Baniachang | BD | 19 | 8458 | 24.51863 | 91.35787 | 60 | 767 | Sylhet District | null Bangladesh | Barguna | BD | 19 | 8459 | 22.13333 | 90.13333 | 06 | 818 | Barisal District | null Bangladesh | Barisal | BD | 19 | 8460 | 22.8 | 90.5 | 06 | 818 | Barisal District | null Bangladesh | Bera | BD | 19 | 8462 | 24.07821 | 89.63262 | 54 | 813 | Rajshahi District | null Bangladesh | Bhairab Bāzār | BD | 19 | 8463 | 24.0524 | 90.9764 | 13 | 771 | Dhaka District | null Bangladesh | Bherāmāra | BD | 19 | 8464 | 24.02452 | 88.99234 | 27 | 811 | Khulna District | null Bangladesh | Bhola | BD | 19 | 8465 | 22.36667 | 90.81667 | 06 | 818 | Barisal District | null Bangladesh | Bhāndāria | BD | 19 | 8466 | 22.48898 | 90.06273 | 06 | 818 | Barisal District | null Bangladesh | Bhātpāra Abhaynagar | BD | 19 | 8467 | 23.01472 | 89.43936 | 27 | 811 | Khulna District | null Bangladesh | Bibir Hat | BD | 19 | 8468 | 22.68347 | 91.79058 | B | 803 | Chittagong Division | null Bangladesh | Bogra | BD | 19 | 8469 | 24.78333 | 89.35 | 54 | 813 | Rajshahi District | null Bangladesh | Brahmanbaria | BD | 19 | 8470 | 23.98333 | 91.16667 | B | 803 | Chittagong Division | null Bangladesh | Burhānuddin | BD | 19 | 8471 | 22.49518 | 90.72391 | 06 | 818 | Barisal District | null Bangladesh | Bājitpur | BD | 19 | 8472 | 24.21623 | 90.95002 | 13 | 771 | Dhaka District | null Bangladesh | Chandpur | BD | 19 | 8474 | 23.25 | 90.83333 | B | 803 | Chittagong Division | null Bangladesh | Chapai Nababganj | BD | 19 | 8475 | 24.68333 | 88.25 | 54 | 813 | Rajshahi District | null (20 rows) -
Count the loaded data:
astra db count dsbulk_demo_db \ -k dsbulk_demo_keyspace \ -t cities_by_countryResult
[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk count -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO [INFO] DSBulk is starting please wait ... Username and password provided but auth provider not specified, inferring PlainTextAuthProvider A cloud secure connect bundle was provided: ignoring all explicit contact points. Operation directory: /Users/USERNAME/logs/COUNT_20250123-021120-127216 total | failed | rows/s | p50ms | p99ms | p999ms 134,574 | 0 | 65,674 | 213.18 | 329.25 | 329.25 Operation COUNT_20250123-021120-127216 completed successfully in 1 second. Checkpoints for the current operation were written to checkpoint.csv. To resume the current operation, re-run it with the same settings, and add the following command line flag: --dsbulk.log.checkpoint.file=/Users/USERNAME/logs/COUNT_20250123-021120-127216/checkpoint.csv 134574 -
Unload the data into CSV files:
astra db unload dsbulk_demo_db \ -k dsbulk_demo_keyspace \ -t cities_by_country \ -url unloaded_dataResult
[INFO] RUNNING: /Users/USERNAME/.astra/dsbulk-1.11.0/bin/dsbulk unload -u token -p AstraCS:FZm... -b /Users/USERNAME/.astra/scb/scb_91b35105-a5aa-4cd5-a93b-900ac58452ba_us-east1.zip -k dsbulk_demo_keyspace -t cities_by_country -logDir ./logs --log.verbosity normal --schema.allowMissingFields true -maxConcurrentQueries AUTO -delim , -url unloaded_data -header true -encoding UTF-8 -skipRecords 0 -maxErrors 100 [INFO] DSBulk is starting please wait ... Username and password provided but auth provider not specified, inferring PlainTextAuthProvider A cloud secure connect bundle was provided: ignoring all explicit contact points. Operation directory: /Users/USERNAME/logs/UNLOAD_20250123-021231-557959 total | failed | rows/s | p50ms | p99ms | p999ms 134,574 | 0 | 29,767 | 281.25 | 591.40 | 591.40 Operation UNLOAD_20250123-021231-557959 completed successfully in 4 seconds. Checkpoints for the current operation were written to checkpoint.csv. To resume the current operation, re-run it with the same settings, and add the following command line flag: --dsbulk.log.checkpoint.file=/Users/USERNAME/logs/UNLOAD_20250123-021231-557959/checkpoint.csvThis command unloads row data from the
cities_by_countrytable, and stores it as CSV files within a subsirectory namesunloaded_datain the same directory where you ran the command.
Configure Change Data Capture (CDC)
|
CDC for Astra DB incurs billed charges based on your Astra Streaming usage. For more information, see Astra Streaming pricing and CDC metering rates. |
CDC for Astra DB automatically captures changes in real time, de-duplicates the changes, and then streams the clean set of changed data into Astra Streaming where it can be processed by client applications or sent to downstream systems.
Use the astra db create-cdc command to create a CDC connection for a table in a Serverless (Non-Vector) database:
astra db create-cdc DATABASE_ID \
-k KEYSPACE_NAME \
--table TABLE_NAME \
--tenant TENANT_NAMEUse the astra db list-cdc command to list the CDC connections for a specifc database:
astra db list-cdc DATABASE_IDResult
+-----------------------+-------------------+----------------+----------------+--------------------+----------------+----------------+
| id | keyspace | table | tenant | cluster | namespace | Status |
+-----------------------+-------------------+----------------+----------------+--------------------+----------------+----------------+
| 57a3024f-cdcdemotable | cdc_demo_keyspace | cdc_demo_table | cdc-demo-tenant| pulsar-aws-useast1 | astracdc | Running |
+-----------------------+-------------------+----------------+----------------+--------------------+----------------+----------------+Use the astra db delete-cdc command to delete a CDC connection for a specific table:
astra db delete-cdc DATABASE_ID \
-k KEYSPACE_NAME \
--table TABLE_NAME \
--tenant TENANT_NAMEdb create-cdc options
Expand to see all db create-cdc options
NAME
astra db create-cdc - Create a CDC to pulsar
SYNOPSIS
astra db create-cdc [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ {-k | --keyspace} <KEYSPACE> ] [ --no-color ]
[ {-o | --output} <FORMAT> ]
[ -p, --partition <PARTITION TOKEN> ] [ --table <TABLE> ]
[ --tenant <TENANT> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-k <KEYSPACE>, --keyspace <KEYSPACE>
Keyspace name
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
-p, --partition <PARTITION TOKEN>
Paritions in the topics
--table <TABLE>
Table name
--tenant <TENANT>
Tenant name
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb list-cdc options
Expand to see all db list-cdc options
NAME
astra db list-cdc - List CDC available on this databse
SYNOPSIS
astra db list-cdc [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ --no-color ] [ {-o | --output} <FORMAT> ]
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierdb delete-cdc options
Expand to see all db delete-cdc options
NAME
astra db delete-cdc - Delete a CDC connection
SYNOPSIS
astra db delete-cdc [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ -id <CDC_ID> ] [ {-k | --keyspace} <KEYSPACE> ]
[ --no-color ] [ {-o | --output} <FORMAT> ] [ --table <TABLE> ]
[ --tenant <TENANT> ] [ --token <AUTH_TOKEN> ]
[ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-id <CDC_ID>
Identifier of the cdc when providing
-k <KEYSPACE>, --keyspace <KEYSPACE>
Keyspace name
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
--table <TABLE>
Table name
--tenant <TENANT>
Tenant name
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierEnd-to-end example
The following end-to-end example shows how to use the Astra CLI to create a CDC connection for a table in a Serverless (Non-Vector) database:
-
Create an Astra DB Serverless (Non-Vector) database:
astra db create cdc_demo_db \ -c aws \ -r us-east-1 \ -k cdc_demo_keyspaceResult
REGION OK [INFO] Database 'cdc_demo_db' does not exist. Creating database 'cdc_demo_db' with keyspace 'cdc_demo_keyspace' get CLoud provider [INFO] Database 'cdc_demo_db' and keyspace 'cdc_demo_keyspace' are being created. [INFO] Database 'cdc_demo_db' has status 'PENDING' waiting to be 'ACTIVE' ... [INFO] Database 'cdc_demo_db' has status 'ACTIVE' (took 112117 millis) [OK] Database 'cdc_demo_db' is ready. -
Create an Astra Streaming tenant in the same region as your database:
astra streaming create cdc-demo-tenant \ -c aws \ -r useast1Result
https://api.astra.datastax.com/v2/streaming/tenants/cdc-demo-tenant [OK] Tenant 'cdc-demo-tenant' has being created. -
Use the CQL shell to create a table with a primary key column in your database.
astra db cqlsh cdc_demo_db -e \ "CREATE TABLE IF NOT EXISTS cdc_demo_keyspace.cdc_demo_table ( \ key text PRIMARY KEY, \ c1 text \ );"Result
[INFO] Cqlsh is starting, please wait for connection establishment... -
Confirm table creation:
astra db cqlsh cdc_demo_db -e \ "SELECT * FROM cdc_demo_keyspace.cdc_demo_table"Result
[INFO] Cqlsh is starting, please wait for connection establishment... key | c1 -----+---- (0 rows) -
Create a CDC connection.
astra db create-cdc cdc_demo_db \ -k cdc_demo_keyspace \ --table cdc_demo_table \ --tenant cdc-demo-tenant -
Confirm CDC details for the database and tenant.
astra db list-cdc cdc_demo_dbResult
+-----------------------+-------------------+----------------+----------------+--------------------+----------------+----------------+ | id | keyspace | table | tenant | cluster | namespace | Status | +-----------------------+-------------------+----------------+----------------+--------------------+----------------+----------------+ | 57a3024f-cdcdemotable | cdc_demo_keyspace | cdc_demo_table | cdc-demo-tenant| pulsar-aws-useast1 | astracdc | Running | +-----------------------+-------------------+----------------+----------------+--------------------+----------------+----------------+astra streaming list-cdc cdc-demo-tenantResult
+--------------------+----------------+----------------+-------------------+----------------+----------------+ | cluster | namespace | database | keyspace | table | status | +--------------------+----------------+----------------+-------------------+----------------+----------------+ | pulsar-aws-useast1 | astracdc | cdc_demo_db | cdc_demo_keyspace | cdc_demo_table | running | +--------------------+----------------+----------------+-------------------+----------------+----------------+
After you enable CDC on your Serverless (Non-Vector) database, you can connect a sink.
Download the Secure Connect Bundle
The Download and use a Secure Connect Bundle (SCB) with Astra DB Serverless is a zip file containing security credentials and certificates required for secure mutual TLS (mTLS) connection to your database.
Use the astra db download-scb command to download the Secure Connect Bundle (SCB) for a database:
astra db download-scb DATABASE_ID -r REGION_NAMEResult
[INFO] Bundle downloaded in ./scb_a53003fe-ba42-4c3c-85d0-6b345622c2dc_dc-1.zipThe -r REGION_NAME option is required for multi-region databases.
If your database is configured with multiple regions, replace REGION_NAME with the name of the region you want to download the SCB for.
By default, the Astra CLI downloads the SCB to the directory where you run the command and saves the file with the following naming pattern: scb_DATABASE-ID_REGION-NAME.zip.
|
Treat the SCB the same way you would any other sensitive values, such as passwords or tokens. The SCB contains sensitive information that establishes a connection to your database, including key pairs and certificates. |
db download-scb options
Expand to see all db download-scb options
NAME
astra db download-scb - Download secure connect bundle archive for a
region
SYNOPSIS
astra db download-scb [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ] [ --env <Environment> ]
[ {-f | --output-file} <DEST> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] [ {-r | --region} <DB_REGION> ]
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
--env <Environment>
Astra Environment to use
-f <DEST>, --output-file <DEST>
Destination file
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
-r <DB_REGION>, --region <DB_REGION>
Cloud provider region
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierUse the -r / --region option to download the SCB for a specific region:
astra db download-scb DATABASE_ID -r REGION_NAMEResult
[INFO] Bundle downloaded in ./scb_a53003fe-ba42-4c3c-85d0-6b345622c2dc_dc-1.zip|
Use the |
Use the -f / --output-file option to download the SCB to a specific location and filename:
astra db download-scb DATABASE_ID -f DESTINATION_FILE.zipResult
[INFO] Bundle downloaded in DESTINATION_FILE.zipCreate environment variables
When developing applications with Astra DB APIs, you will notice common values that are frequently reused, such as application tokens, database API endpoints, database IDs, and keyspace names. It’s a good practice to store these values in environment variables to facilitate reuse in your scripts, simplify token rotation, and increase security by keeping sensitive information separate from your core application code.
The Astra CLI can automatically generate a set of relevant variables for a database that you can use in your applications.
Use the astra db create-dotenv command to generate a .env file containing relevant environment variables for a specific database:
astra db create-dotenv DATABASE_IDBy default, the Astra CLI saves the .env file to the directory where you run the command.
If a .env file already exists in the directory, the Astra CLI appends the new environment variables to the existing file.
Result
.env
ASTRA_DB_API_ENDPOINT="https://a53003fe-ba42-4c3c-85d0-6b345622c2dc-us-east1.apps.astra.datastax.com/api/json"
ASTRA_DB_APPLICATION_TOKEN="AstraCS:FZm..."
ASTRA_DB_GRAPHQL_URL="https://a53003fe-ba42-4c3c-85d0-6b345622c2dc-us-east1.apps.astra.datastax.com/api/graphql/demo"
ASTRA_DB_GRAPHQL_URL_ADMIN="https://a53003fe-ba42-4c3c-85d0-6b345622c2dc-us-east1.apps.astra.datastax.com/api/graphql-admin"
ASTRA_DB_GRAPHQL_URL_PLAYGROUND="https://a53003fe-ba42-4c3c-85d0-6b345622c2dc-us-east1.apps.astra.datastax.com/api/playground"
ASTRA_DB_GRAPHQL_URL_SCHEMA="https://a53003fe-ba42-4c3c-85d0-6b345622c2dc-us-east1.apps.astra.datastax.com/api/graphql-schema"
ASTRA_DB_ID="a53003fe-ba42-4c3c-85d0-6b345622c2dc"
ASTRA_DB_KEYSPACE="demo"
ASTRA_DB_REGION="us-east1"
ASTRA_DB_REST_URL="https://a53003fe-ba42-4c3c-85d0-6b345622c2dc-us-east1.apps.astra.datastax.com/api/rest"
ASTRA_DB_REST_URL_SWAGGER="https://a53003fe-ba42-4c3c-85d0-6b345622c2dc-us-east1.apps.astra.datastax.com/api/rest/swagger-ui/"
ASTRA_DB_SECURE_BUNDLE_PATH="/Users/USERNAME/.astra/scb/scb_a53003fe-ba42-4c3c-85d0-6b345622c2dc_us-east1.zip"
ASTRA_DB_SECURE_BUNDLE_URL="https://datastax-cluster-config-prod.s3.us-east-2.amazonaws.com/a53003fe-ba42-4c3c-85d0-6b345622c2dc-1/secure-connect-demo.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA2AIQRQ76XML7FLD6%2F20241120%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20241120T233147Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=46d8704e382458c82d7da02db1ca79657e003de327f0123a0189ec1a50171cb0"
ASTRA_ORG_ID="2dbd3c55-6a68-4b5b-9155-5be9d41823e8"
ASTRA_ORG_NAME="alice@example.com"
ASTRA_ORG_TOKEN="AstraCS:FZm..."|
The generated The SCB contains sensitive information that establishes a connection to your database, including key pairs and certificates. |
db create-dotenv options
Expand to see all db create-dotenv options
NAME
astra db create-dotenv - Generate an .env configuration file associate
with the db
SYNOPSIS
astra db create-dotenv [ {-cf | --config-file} <CONFIG_FILE> ]
[ {-conf | --config} <CONFIG_SECTION> ]
[ {-d | --directory} <DIRECTORY> ] [ --env <Environment> ]
[ {-k | --keyspace} <KEYSPACE> ] [ --no-color ]
[ {-o | --output} <FORMAT> ] [ {-r | --region} <DB_REGION> ]
[ --token <AUTH_TOKEN> ] [ {-v | --verbose} ] [--] <DB>
OPTIONS
-cf <CONFIG_FILE>, --config-file <CONFIG_FILE>
Configuration file (default = ~/.astrarc)
-conf <CONFIG_SECTION>, --config <CONFIG_SECTION>
Section in configuration file (default = ~/.astrarc)
-d <DIRECTORY>, --directory <DIRECTORY>
Destination for the config file
--env <Environment>
Astra Environment to use
-k <KEYSPACE>, --keyspace <KEYSPACE>
Default keyspace created with the Db
--no-color
Remove all colors in output
-o <FORMAT>, --output <FORMAT>
Output format, valid values are: human,json,csv
-r <DB_REGION>, --region <DB_REGION>
Cloud provider region
--token <AUTH_TOKEN>
Key to use authenticate each call.
-v, --verbose
Verbose mode with log in console
--
This option can be used to separate command-line options from the
list of arguments (useful when arguments might be mistaken for
command-line options)
<DB>
Database name (if unique) or Database identifierUse the -d / --directory option to save the .env file to a specific directory:
astra db create-dotenv DATABASE_ID -d ~/tmpResult
[OK] File '/Users/USERNAME/tmp/.env' has been created/amended|
The directory must already exist before you run the command.
If the directory doesn’t exist, the Astra CLI will report the following error: |
