docs(destination-chroma): correct sync modes and document all config options

[devin-ai-integration]

Triggering Context

Run triggered by: Automated autodoc run for a connector commit merged to master.

Relevant context: Source commit 16b8dfd (destination-chroma 0.0.54 → 0.0.55, CDK bump for CVE-2025-68664), from #84361.

Confidence impact: The trigger was a small, already-merged dependency PR with unambiguous scope, so the triggering context is clear and scores high.

Documentation Confidence Assessment

Overall Confidence: 3/5

Dimension	Score	Rationale
Code Comprehension of the Documented Surface	4/5	Python CDK baseline 3, adjusted up for shared vector-DB CDK leverage, a small documented path with no custom components, and unit tests covering collection-name and path validation.
API Documentation Quality	4/5	Chroma publishes good official docs for client modes, auth, and embedding functions; rate-limit and server-behavior details are thin.
Change Scope & Risk	3/5	111 lines changed: sync-mode table correction, new output-schema and configuration sections, some reorganization.
Existing Doc Maturity	2/5	The prose was roughly 75 lines of sparse setup notes, with the rest of the file being changelog.
Connector Sensitivity	5/5	Community connector, alpha release stage, OSS-only (cloud disabled in metadata.yaml).
Triggering Context	5/5	Small merged dependency PR with a known connector and version.
Inference Ratio	4/5	Nearly every claim traces to connector source, CDK source, unit tests, or Chroma docs; a few statements about operator experience are reasoned rather than observed.

Adjustments based on code comprehension

• Framework leverage: upward — chunking, embedding, and dedup behavior come from airbyte_cdk/destinations/vector_db_based (Writer, Embedder, DocumentProcessor), which is shared and separately documented; only indexer.py is connector-specific.
• Custom-component budget: upward — the documented path is destination.py, indexer.py, config.py, utils.py, no_embedder.py; no dynamic dispatch or feature flags.
• Test coverage of the documented claim: upward — unit_tests/test_indexer.py asserts the collection-name rules and the /local/ path prefix requirement that this PR documents.
• Independent corroboration: upward — collection-name rules and client modes appear both in connector code and in Chroma's own documentation; the pinned chromadb==0.6.3 bound corroborates the name-length constraint.

What I Verified vs. What I Inferred

• Verified from code:
  • All streams land in one collection named in the config, one document per chunk, with a generated UUID document ID (indexer.py, CDK DocumentProcessor).
  • Overwrite deletes only documents whose _ab_stream matches the overwritten streams, rather than dropping the collection (ChromaIndexer.pre_sync / _delete_by_filter).
  • Dedup deletes by _ab_record_id before writing (delete, CDK Writer).
  • Supported destination sync modes are overwrite, append, append_dedup with supportsIncremental=True (destination.py), so the old Full Refresh - Overwrite + Deduped row was wrong.
  • Batch size is 128 chunks (destination.py).
  • Collection-name rules and the /local/ path prefix check (utils.py, indexer.py, unit_tests/test_indexer.py).
  • Basic auth is only applied when both username and password are set (_get_client).
  • NoEmbedder sends None embeddings, so Chroma computes them.
  • Embedding option dimensions (1536 for OpenAI/Azure/Fake) and the From Field length check that fails the sync on a mismatch (CDK embedder.py).
  • Chunk size max 8191, chunk overlap default 0, and metadata JSON-encoding of non-scalar values (CDK config.py, document_processor.py).
• Verified from API docs: Chroma's HTTP client/server and persistent client modes, basic-auth client provider, collection-name constraints, and the default embedding function (all-MiniLM-L6-v2) running locally.
• Inferred: that the default embedding function is better suited to smaller/prototype loads is stated only as "runs on the machine running Chroma" now; the Kubernetes restriction is carried over from the existing docs without an explanatory cause; the VPC/network-access guidance is carried over from the existing docs.

Areas of Concern

• The Kubernetes restriction on Persistent Client Mode is preserved from the previous docs. I could not find a source explaining it, so I kept it as a bare statement.
• The /local → /tmp/airbyte_local mapping and macOS file-sharing guidance is rewritten from the previous docs and applies to Docker-based OSS deployments; a reviewer familiar with current abctl deployments should confirm it is still accurate.

Changelog validation

0.0.55 links to [84361] → .../pull/84361 (match). The version-bump commit 16b8dfd landed on master on 2026-08-13, which matches the changelog date. No changelog corrections were needed.

---

What

Rewrites the user documentation for the Chroma destination so it matches the connector's actual behavior and documents the configuration options that were previously missing.

How

Corrections

• Removed the unsupported Full Refresh - Overwrite + Deduped sync mode row.
• Replaced "validated and corrected by Airbyte" with the actual behavior: the connector validates the collection name and fails the check with a specific error.
• Corrected the output-schema description: one document per chunk (not per record), embeddings omitted in default-embedding mode, and metadata values coerced to strings when they aren't scalars.
• Replaced the generic "supports namespaces" line with what actually happens: namespaces are encoded in the _ab_stream metadata value, not separate collections.
• Fixed the "cient/server mode" typo.

Additions

• Prerequisites section.
• What overwrite and deduplicating syncs delete, and that dedup needs a primary key.
• The connector-generated metadata fields _ab_stream and _ab_record_id.
• The full collection-name rules.
• All seven embedding options, including Azure OpenAI, OpenAI-compatible, From Field, and Fake, with their dimensions and required credentials.
• Processing options: chunk size limit, chunk overlap, text/metadata field selection, text splitter, field name mappings, and the effect of Do not store raw text.
• The 128-chunk write batch size.

Formatting

• Normalized the changelog table's column separators to satisfy MarkdownLint MD060. No changelog rows or values were changed.

Removals / restructuring

• Dropped the "Getting Started (Airbyte Open Source)" framing and the duplicated field checklist, folding both into task-shaped setup sections.

Review Guide

• Sync mode table and the two paragraphs below it (lines 13--24): the behavior claims that changed most.
• Connection mode section (lines 43--66): carried-over Docker/Kubernetes guidance worth a sanity check.
• Embedding section (lines 80--90): option names should match the connector spec titles in the UI.

Verification

• MarkdownLint (markdownlint-cli2) on the changed file: 0 errors.
• CI on this PR is green, including Docs / Vale, Docs / MarkDownLint, and Build Airbyte Docs.
• The local Docusaurus pnpm build could not run in this environment (node_modules not installed, docusaurus: not found). The CI docs build covers the same check and passed.
• GitHub Copilot review could not be requested: the automation reported that the Copilot review PAT is not configured.

User Impact

Readers get accurate sync-mode behavior, the metadata fields they need to filter on when querying Chroma, and documentation for configuration options that previously had none.

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 Chroma's official 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-7lsc1ysn3-airbyte-growth.vercel.app
Latest Commit:	06b6ace

Deployed with vercel-action