Untitled :: DataStax Astra DB Classic Documentation

Creating a namespace

In order to use the Document API, you must create the namespace as a container that will store collections, which in turn store documents. Documents can themselves hold multiple documents. Multiple collections are contained in a namespace, but a collection cannot be contained in multiple namespaces.

Only namespaces need to be specifically created. Collections are specified when a document is inserted. An optional setting, replicas, defines the number of data replicas the database will store for the namespace. If no replica is defined, then for a namespace in a single datacenter cluster, the default is 1, and for a multiple-datacenter cluster, the default is 3 for each datacenter.

Simple namespace

Send a POST request to /api/docs/v2/schemas/namespaces. In this example we use myworld for the name, and no replicas setting, to default to 1.

cURL command (/v2)
Result

curl --location --request POST 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/docs/v2/namespaces' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "name": "myworld"
}'

{"name":"myworld"}

The authorization token and the content type are passed with --header. The token must be identified as X-Cassandra-Token so that cluster recognizes the token and its value. The specified name for the namespace is passed as JSON data using --data. For shorthand, cURL can use:

-L for --location
-X for --request
-H for --header
-d for --data

Set replicas in simple namespace

To set the replicas, send a POST request to /api/docs/v2/schemas/namespaces. In this example we use myworld for the name, and 2 for the number of data replicas.

cURL command (/v2)
Result

curl -L -X POST 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/docs/v2/schemas/namespaces' \
-H "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
    "name": "myworld",
    "replicas": 1
}'

{"name":"myworld"}

Namespace for multiple datacenters

For a multiple-datacenter cluster, a namespace is defined datacenters. Send a POST request to /api/docs/v2/schemas/namespaces. In this example we use myworld-dcs for the name, the datacenters are dc1 and dc2, where dc1 defaults to 3 replicas and dc2 is set to 5 replicas.

cURL command (/v2)
Result

curl -L -X POST 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/docs/v2/schemas/namespaces' \
-H "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
    "name": "myworld_dcs",
    "datacenters": [ {"name": "dc1"}, {"name": "dc2", "replicas": 5} ]
}'

{"name":"myworld_dcs"}