docs(destination-astra): document setup, storage model, and limits

[devin-ai-integration]

Triggering Context

Run triggered by: Automated docs review of a commit merged to master — fix(destination-astra): bump CDK to remediate CVE-2025-68664 in langchain (version 0.1.45).

Relevant context: #84359 (commit 4e2b4e99a6a7cbcee101a12b5573a7401c05fdad)

Confidence impact: The trigger is a small, already-merged dependency bump with unambiguous scope, so the triggering context itself introduces no uncertainty; the uncertainty in this PR comes from the broader doc gaps I chose to fix, not from the trigger.

Documentation Confidence Assessment

Overall Confidence: 3/5

Dimension	Score	Rationale
Code Comprehension of the Documented Surface	4/5	Read the full connector (config.py, destination.py, indexer.py, astra_client.py) plus the shared vector-db CDK writer and document processor; the documented path has no custom components beyond a thin HTTP client.
API Documentation Quality	4/5	DataStax publishes thorough Data API docs covering tokens, roles, collection management, indexing, and explicit limits; the links in metadata.yaml point at older astra-serverless paths.
Change Scope & Risk	3/5	62 lines added, 21 removed in a single doc: new prerequisites, storage model, sync-mode behavior, and limitations sections.
Existing Doc Maturity	2/5	The pre-existing doc was 98 lines, most of it changelog, with a setup guide and no configuration or behavior documentation.
Connector Sensitivity	5/5	destination-astra is a community, alpha-stage connector with no ab_internal quality/support levels set.
Triggering Context	5/5	Triggered by a small merged PR (CDK version bump).
Inference Ratio	4/5	Nearly all claims trace to connector code or DataStax docs; a small amount of operational guidance is reasoned from those two sources rather than stated outright anywhere.

Adjustments based on code comprehension

Baseline 3 (Python CDK), adjusted to 4:

• Declarative surface area: upward — the configuration options, required fields, and the five embedding modes come from integration_tests/spec.json and destination_astra/config.py, not from imperative code.
• Framework leverage / custom-component budget: upward — chunking, embedding, and deduplication come from the separately maintained airbyte_cdk.destinations.vector_db_based package; the connector-specific code is AstraIndexer plus a small AstraClient that issues Data API commands, both of which I read end to end.
• Independent corroboration: upward — the collection auto-creation, cosine metric, and x-cassandra-token auth in the code line up with the DataStax Data API docs for createCollection and application tokens.
• No empirical verification: downward — I did not run a sync against a live Astra database, so the failure mode described in the last bullet of "Limitations" is reasoned from documented Astra behavior rather than observed.

What I Verified vs. What I Inferred

• Verified from code: the four required Astra config fields and their meanings; the connector creates the configured collection when find_collection returns false; collections are created with the cosine metric and the embedder's dimension; documents carry _id (a UUID), $vector, text (unless Do not store raw text is set), _ab_stream, _ab_record_id, and the configured metadata fields; overwrite deletes only documents matching _ab_stream for the synced stream; deduplication deletes by _ab_record_id; all streams share one collection and the namespace is folded into _ab_stream; the five embedding modes and that OpenAI-compatible requires an explicit dimensions value; supported sync modes come from spec().
• Verified from API docs: a token generated from the database Overview tab gets a database-scoped Database Administrator role, which can create collections; default_keyspace exists on new Serverless (Vector) databases; the 4,096-dimension ceiling, approximately 10 collections per database, the 64-field-per-collection limit, and the 8,000-byte indexed string limit; collections created without an indexing clause index every field.
• Inferred: that exceeding the 8,000-byte indexed string limit surfaces as an insert failure a user would resolve by lowering the chunk size (both premises are documented; the resulting operator guidance is mine); that a fixed collection dimension means you should point a new embedding model at a new collection.

Areas of Concern

• The last bullet of "Limitations" (8,000-byte indexed strings vs. chunk size) is the one place where I combine two documented facts into operator guidance. If DataStax truncates or silently drops instead of rejecting, that bullet should be reworded.
• The "64 distinct fields per collection" limit is documented for collections generally; I state that configured metadata fields count toward it, which follows from the connector writing metadata as top-level document fields but is worth a second look.
• I removed the old Pre-Requisites line that listed only an embedding API key. The new list is longer; confirm nothing you consider essential dropped out.

---

What

The Astra DB destination doc explained how to create an Astra database and where to copy the endpoint and token, and nothing else. It didn't say what the connector writes, which token permissions it needs, that it creates the collection for you, how each sync mode behaves, or which Astra limits you can run into. Anyone setting the connector up had to read the connector source to answer basic operational questions.

This PR fills those gaps and corrects the prerequisites, which previously listed an embedding API key as the only requirement.

How

Corrections

• Replaced the single-item Pre-Requisites list with the connector's actual requirements: a Serverless (Vector) database and endpoint, an application token that can create collections and read and write in the keyspace, a keyspace, a collection name, and an embedding API key (not required for the Fake embedder).
• Converted the two #38181 / #37405 changelog entries into links matching the format of the rest of the table.

Additions

• An intro sentence describing what the connector does with each record (concatenate text fields, chunk, embed, write one document per chunk).
• "Choose an embedding service": the collection's dimension is fixed at creation, OpenAI-compatible requires you to supply the dimension, and what the Fake embedder is for.
• "How the connector stores data": the document fields (_id, $vector, text, _ab_stream, _ab_record_id, metadata fields), and that all streams share one collection.
• Per-sync-mode behavior under the existing support table, including that deduplicated modes need a primary key.
• "Limitations": fixed collection dimension, the 64-field and collection-count limits, and the 8,000-byte indexed string limit.
• A note that a namespace becomes part of _ab_stream rather than creating a keyspace or collection.

Restructuring

• Split the setup guide into "Set up an Astra DB database" and "Get the endpoint and token", promoted both to ## headings (the doc previously jumped from ## to ####), and converted the setup steps to numbered lists with real sub-steps instead of -- prefixed lines.
• Referred to fields by their UI labels (Astra DB Endpoint, Astra DB Application Token) instead of their raw spec names (astra_db_endpoint, astra_db_app_token).

Changelog validation

• Version 0.1.45's entry links to fix(destination-astra): bump CDK to remediate CVE-2025-68664 in langchain #84359 with matching link text, and that PR merged on 2026-08-13, which matches the date in the table. No date correction was needed.

Review Guide

1. docs/integrations/destinations/astra.md lines 7–13 (prerequisites) — the token permission claim is the one most likely to trip a user up if it's wrong.
2. Lines 41–54 ("How the connector stores data") — check against destination_astra/indexer.py::index and the CDK's document_processor.py.
3. Lines 66–70 (sync mode behavior) — check against indexer.py::pre_sync and indexer.py::delete.
4. Lines 76–83 ("Limitations") — the section most worth a skeptical read; see "Areas of Concern".

User Impact

You can set up the Astra destination and predict what it writes without reading the connector source. No connector behavior changes.

Can this PR be safely reverted and rolled back?

• YES 💚
• NO ❌

---

Note: I am an AI assistant (Devin) and have proposed these documentation updates based on a review of the connector source code and third-party API documentation. Reviewers may merge, modify, or close this PR as they see fit.

---

Devin session

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

PR Slash Commands

Airbyte Maintainers (that's you!) can execute the following slash commands on your PR:

• 🛠️ Quick Fixes
  • /format-fix - Fixes most formatting issues.
  • /bump-version - Bumps connector versions, scraping changelog description from the PR title.
    • Bump types: patch (default), minor, major, major_rc, rc, promote.
    • The rc type is a smart default: applies minor_rc if stable, or bumps the RC number if already RC.
    • The promote type strips the RC suffix to finalize a release.
    • Example: /bump-version type=rc or /bump-version type=minor
  • /bump-progressive-rollout-version - Alias for /bump-version type=rc. Bumps with an RC suffix and enables progressive rollout.
• ❇️ AI Testing and Review (internal link: AI-SDLC Docs):
  • /ai-prove-fix - Runs prerelease readiness checks, including testing against customer connections.
  • /ai-canary-prerelease - Rolls out prerelease to 5-10 connections for canary testing.
  • /ai-review - AI-powered PR review for connector safety and quality gates.
• 📝 AI Documentation:
  • /ai-docs-review - AI-powered documentation review for PRs with connector changes.
  • /ai-create-docs-pr - Creates a documentation PR for connector changes, stacked on the current PR.
• 🚀 Connector Releases:
  • /publish-connectors-prerelease - Publishes pre-release connector builds (tagged as {version}-preview.{git-sha}) for all modified connectors in the PR.
  • /enable-autopilot-rollouts - Enables autopilot progressive rollouts for the modified connector(s) in the PR, remediating "autopilot rollouts not enabled for {connector-name}" auto-merge blockers. Sets defaultRolloutMode: autopilot and enableProgressiveRollout: true, preserving any existing autopilotConfig.
    • Optional args: connector=<CONNECTOR_NAME> (defaults to the modified connectors in the PR), strategy=fast|slow|default (defaults to fast).
    • Example: /enable-autopilot-rollouts or /enable-autopilot-rollouts connector=source-faker strategy=slow
• ☕️ JVM connectors:
  • /update-connector-cdk-version connector=<CONNECTOR_NAME> - Updates the specified connector to the latest CDK version.
    Example: /update-connector-cdk-version connector=destination-bigquery
• 🐍 Python connectors:
  • /poe connector source-example lock - Run the Poe lock task on the source-example connector, committing the results back to the branch.
  • /poe source example lock - Alias for /poe connector source-example lock.
  • /poe source example use-cdk-branch my/branch - Pin the source-example CDK reference to the branch name specified.
  • /poe source example use-cdk-latest - Update the source-example CDK dependency to the latest available version.
• ⚙️ Admin commands:
  • /force-merge reason="<REASON>" - Force merges the PR using admin privileges, bypassing CI checks. Requires a reason.
    Example: /force-merge reason="CI is flaky, tests pass locally"

📚 Show Repo Guidance

Helpful Resources

• Breaking Changes Guide - Breaking changes, migration guides, and upgrade deadlines
• Developing Connectors Locally
• Managing Connector Secrets
• On-Demand Regression Tests
• #connector-ci-issues
• #connector-publish-updates
• #connector-build-statuses

📝 Edit this welcome message.

[github-actions]

Deploy preview for airbyte-docs ready!

Project:	airbyte-docs
Status:	✅  Deploy successful!
Preview URL:	https://airbyte-docs-56la465bb-airbyte-growth.vercel.app
Latest Commit:	758e80b

Deployed with vercel-action