diff --git a/docs-src/astra-cli-core/antora.yml b/docs-src/astra-cli-core/antora.yml index 7e50f45..00147f0 100644 --- a/docs-src/astra-cli-core/antora.yml +++ b/docs-src/astra-cli-core/antora.yml @@ -8,19 +8,25 @@ nav: asciidoc: attributes: + # General attributes + company: 'DataStax' + support-url: 'https://support.datastax.com' + # Other product attributes + cass-reg: 'Apache Cassandra(R)' + cass: 'Apache Cassandra' + cass-short: 'Cassandra' + # Astra DB attributes + astra-db: 'Astra DB' + astra: 'Astra' product: 'Astra CLI' product-version: '0.6' - astra: 'Astra' db-serverless: 'Serverless (Non-Vector)' db-serverless-vector: 'Serverless (Vector)' db-classic: 'Classic' - astra-api: 'Data API' - url-astra: 'https://astra.datastax.com' - link-astra-portal: '{url-astra}[{astra_ui}^]' - py-client-api-ref-url: 'xref:astra-api-docs:ROOT:attachment$python-client/astrapy' - ts-client-api-ref-url: 'xref:astra-api-docs:ROOT:attachment$typescript-client' - java-client-api-ref-url: 'xref:astra-api-docs:ROOT:attachment$java-client' - cass-short: 'Cassandra' - scb-long: Secure Connect Bundle (SCB) - scb-cap: Secure Connect Bundle - scb: SCB + astra-stream: 'Astra Streaming' + astra-ui: 'Astra Portal' + astra-url: 'https://astra.datastax.com' + astra-ui-link: '{astra-url}[{astra-ui}^]' + scb: 'Secure Connect Bundle (SCB)' + scb-short: 'SCB' + scb-brief: 'Secure Connect Bundle' \ No newline at end of file diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc index 7bd7fa6..baff8a7 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/getting-started.adoc @@ -11,7 +11,7 @@ To configure the {product}: * xref:ROOT:installation.adoc[Install the {product}]. -* You must have an active {url-astra}[Astra account^]. +* You must have an active {astra-url}[Astra account^]. * [[get-credentials]]You must have an xref:astra-db-serverless:administration:manage-application-tokens.adoc[application token] that is assigned a _role_ with adequate _permissions_ to perform the tasks you'd like to accomplish with the {product}. diff --git a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc index de59221..5dc7f61 100644 --- a/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc +++ b/docs-src/astra-cli-core/modules/ROOT/pages/managing.adoc @@ -54,10 +54,12 @@ astra db create **DATABASE_NAME** --vector ---- ==== -[NOTE] +[IMPORTANT] ==== -You cannot create {db-classic} databases with the {product}. +* **{db-classic} databases**: You cannot create {db-classic} databases with the {product}. However, you can use the {product} to <> about existing {db-classic} databases. + +* **PCU groups**: For organizations on *Enterprise* plans that require new databases to belong to a xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU group], you must xref:astra-db-serverless:databases:create-database.adoc[use the {astra-ui} to create databases] because the {product} doesn't support PCU group assignment with database creation. ==== 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. @@ -521,11 +523,11 @@ You cannot load vector data into a non-vector collection. ===== -- -Use an {astra}-hosted provider:: +Use an Astra-hosted provider:: + -- To automatically generate embeddings with xref:astra-db-serverless:databases:embedding-generation.adoc[{astra_db} vectorize], add an embedding provider integration to your collection. -Embedding provider integrations are either {astra}-hosted or external. +Embedding provider integrations are either Astra-hosted or external. [source,bash,subs="+quotes"] ---- @@ -540,7 +542,7 @@ astra db create-collection **DATABASE_ID** \ Replace the following: * `**COLLECTION_NAME**`: The name of the collection you want to create. -* `**PROVIDER_NAME**`: The name of the {astra}-hosted embedding provider. +* `**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. @@ -574,7 +576,7 @@ Use an external provider:: + -- To automatically generate embeddings with xref:astra-db-serverless:databases:embedding-generation.adoc[{astra_db} vectorize], add an embedding provider integration to your collection. -Embedding provider integrations are either {astra}-hosted or external. +Embedding provider integrations are either Astra-hosted or external. To use an external embedding provider, you must add an xref:astra-db-serverless:databases:embedding-generation.adoc#supported-embedding-providers[embedding provider integration] to your {astra_db} organization, and then you can select that embedding provider when you create a collection. @@ -592,7 +594,7 @@ astra db create-collection **DATABASE_ID** \ Replace the following: * `**COLLECTION_NAME**`: The name of the collection you want to create. -* `**PROVIDER_NAME**`: The name of the {astra}-hosted embedding provider. +* `**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. @@ -2266,10 +2268,16 @@ For more information, see xref:astra-db-serverless:databases:manage-regions.adoc [IMPORTANT] ==== -Multi-region databases are a premium feature. +* **Premium feature**: 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 xref:astra-db-serverless:administration:subscription-plans.adoc[]. + +* **Status change**: The database enters *Maintenance* status while provisioning and replicating data to the new region. +While in *Maintenance* status, you cannot add or remove regions, truncate tables, or delete keyspaces, tables, or collections. +However, *Maintenance* status doesn't impact reads and writes. + +* **PCU groups**: For organizations on *Enterprise* plans that require use of xref:astra-db-serverless:administration:provisioned-capacity-units.adoc[PCU groups], you must xref:astra-db-serverless:databases:manage-regions.adoc[use the {astra-ui} to add regions] because the {product} doesn't support PCU group assignment when adding a region. ==== Use the `astra db create-region` command to add a region to a database: @@ -2304,15 +2312,6 @@ For more information, see xref:astra-db-serverless:databases:regions.adoc[]. ==== //// -[NOTE] -==== -The database enters *Maintenance* status while provisioning and replicating data to the new region. - -While in *Maintenance* status, you cannot 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: [source,bash,subs="+quotes"] @@ -2954,7 +2953,7 @@ token@cqlsh> Type `exit` or `quit;` and press kbd:[Return] to exit `cqlsh`. The first time you use the `astra db cqlsh` command, the {product} downloads and installs the `cqlsh` utility to the {product} installation directory (`~/.astra/cqlsh-astra`). -The {product} also downloads the {scb-long} for each database you connect to and stores the {scb} zip files in the `~/.astra/scb` directory. +The {product} also downloads the {scb} for each database you connect to and stores the {scb-short} zip files in the `~/.astra/scb` directory. [NOTE] ====== @@ -3313,7 +3312,7 @@ To resume the current operation, re-run it with the same settings, and add the f [NOTE] ==== The first time you use one of the `astra db load`, `astra db unload`, or `astra db count` commands, the {product} downloads and installs the `dsbulk` utility to the {product} installation directory (`~/.astra/dsbulk-*`). -The {product} also downloads the {scb-long} for each database you connect to and stores the {scb} zip files in the `~/.astra/scb` directory. +The {product} also downloads the {scb} for each database you connect to and stores the {scb-short} zip files in the `~/.astra/scb` directory. ==== === `db load` options @@ -4227,11 +4226,11 @@ astra streaming list-cdc cdc-demo-tenant After you enable CDC on your {db-serverless} database, you can xref:astra-db-serverless:databases:change-data-capture.adoc#connect-a-sink[connect a sink]. -== Download the {scb-cap} +== Download the {scb-brief} The xref:astra-db-serverless:drivers:secure-connect-bundle.adoc[] 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 {scb-long} for a database: +Use the `astra db download-scb` command to download the {scb} for a database: [source,bash,subs="+quotes"] ---- @@ -4248,15 +4247,15 @@ astra db download-scb **DATABASE_ID** -r **REGION_NAME** ==== The `-r **REGION_NAME**` option is required for <>. -If your database is configured with multiple regions, replace `**REGION_NAME**` with the name of the region you want to download the {scb} for. +If your database is configured with multiple regions, replace `**REGION_NAME**` with the name of the region you want to download the {scb-short} for. -By default, the {product} 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`. +By default, the {product} downloads the {scb-short} to the directory where you run the command and saves the file with the following naming pattern: `scb_**DATABASE-ID**_**REGION-NAME**.zip`. [WARNING] ==== -Treat the {scb} the same way you would any other sensitive values, such as passwords or tokens. +Treat the {scb-short} 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. +The {scb-short} contains sensitive information that establishes a connection to your database, including key pairs and certificates. ==== === `db download-scb` options @@ -4315,7 +4314,7 @@ OPTIONS ---- ==== -Use the `-r` / `--region` option to download the {scb} for a specific region: +Use the `-r` / `--region` option to download the {scb-short} for a specific region: [source,bash,subs="+quotes"] ---- @@ -4337,7 +4336,7 @@ Use the `astra db list-regions` command to get a list of the region names where For more information, see <>. ==== -Use the `-f` / `--output-file` option to download the {scb} to a specific location and filename: +Use the `-f` / `--output-file` option to download the {scb-short} to a specific location and filename: [source,bash,subs="+quotes"] ---- @@ -4400,7 +4399,7 @@ ASTRA_ORG_TOKEN="AstraCS:FZm..." ==== The generated `.env` files contains sensitive information, including the application token that the {product} uses to connect to Astra. -The {scb} contains sensitive information that establishes a connection to your database, including key pairs and certificates. +The {scb-short} contains sensitive information that establishes a connection to your database, including key pairs and certificates. ==== === `db create-dotenv` options