You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
TL;DR: Teach agents that a connection’s loading schema can differ from the destination’s default query context, and expose those overrides in destination guidance.
Updates execute_external_sql_query, describe_connector, and the existing connector-doc namespace inference path rather than introducing a second inference mechanism.
The single Cloud MCP eval run tested initial commit 57cc1b7: 0 passed, 125 startup errors, zero agent tool calls. Scenarios still require names such as list_cloud_connections, but the server exposes list_connections; the rename is already present in this PR’s RC merge base. The harness rejects its allowed-tool list before invoking any model. This provides no behavioral verdict on the change. No rerun was performed; follow-up transport/quoting fixes are covered by the local regressions below.
Changes
Explain database/schema/table naming: BigQuery project/dataset/table; Snowflake database/schema/table. Generate project/database-qualified table examples when configuration is known, using Snowflake identifier escaping.
Enrich server-served destination overviews with per-connection loading schema overrides and table prefixes, reusing existing connection metadata. Section-scoped server docs remain unchanged.
Keep source-derived namespaces and custom templates advisory; unresolved templates are not returned as concrete destination_schema values.
Clarify that loading hints are neither exhaustive inventory nor authorization boundaries. Preserve server docs with a visible warning when connection hints cannot be fetched, including Cloud API and transport failures.
Deployment dependency
The SHOW DATABASES/SHOW TABLES guidance describes the three-part behavior from Sonar #7156; deploy that backend change before releasing this companion. This does not advertise the explicit-context syntax from #7159.
Test plan
uv run pytest tests/unit_tests/test_cloud_describe.py tests/unit_tests/test_mcp_cloud.py -q: 264 passed.
uv run ruff check airbyte/_direct_connectors/connector_docs.py airbyte/mcp/cloud.py tests/unit_tests/test_cloud_describe.py: passed; formatter applied.
uv run pyrefly check: 0 errors (73 suppressed).
Repository uv run poe check: passed (exit 0).
No customer credentials or live customer queries used.
Here are some helpful tips and reminders for your convenience.
💡 Show Tips and Tricks
Testing This PyAirbyte Version
You can test this version of PyAirbyte using the following:
# Run PyAirbyte CLI from this branch:
uvx --from 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1793208519-mcp-destination-schema-hints' pyairbyte --help
# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1793208519-mcp-destination-schema-hints'
PR Slash Commands
Airbyte Maintainers can execute the following slash commands on your PR:
/fix-pr - Fixes most formatting and linting issues
/uv-lock - Updates uv.lock file
/test-pr - Runs tests with the updated PyAirbyte
/prerelease - Builds and publishes a prerelease version to PyPI
/evals - Runs the Cloud MCP evals that use the MCP tools this PR changed (/evals full=true runs the full suite)
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
A timeout or connection failure in the raw-JSON fallback escapes the handler, discarding the successfully fetched server overview instead of preserving it with a warning.
Adding the database verbatim produces invalid examples for valid Snowflake database names that require quoting. For example, database="ANALYTICS-PROD" and schema="RAW" now generate SELECT * FROM ANALYTICS-PROD.RAW.<table> LIMIT 10; the database component must be quoted as a single identifier. Please apply Snowflake-aware identifier quoting/escaping to the newly added database component and cover a special-character database name in the example tests.
On it. The newly added database qualifier needs escaping when the configured Snowflake identifier contains special characters, as noted in the latest review. I’m correcting the example formatting and adding regressions without changing ordinary unquoted-name resolution.
Resolved in c6d665f. Addressed the Snowflake example review with the existing Snowflake SQLAlchemy identifier preparer, not a new quoting implementation. Regressions cover hyphens, embedded dots, escaped quotes, reserved words, and ordinary lowercase names. All 264 focused tests and repository poe check pass.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
The SQL discovery guidance depends on inaccessible Sonar #7156, so its SHOW DATABASES/SHOW TABLES contract and required deployment order need human verification.
Verified; rollout dependency retained. In response to the cross-repo review, I checked the Sonar provider implementations and their tests locally: SHOW DATABASES identifies the configured BigQuery project/Snowflake database, while SHOW TABLES spans that context’s schemas (BigQuery remains query-location-scoped). Ordinary query defaults are unchanged.
As the description states, deploy Sonar #7156before releasing this companion. Sonar #7159 is optional for this PR: the MCP guidance does not advertise its explicit-context syntax. No additional behavior change is needed here.
Hola, AJ. No remaining Sonar merge/deployment dependency. In answer to your question:
Sonar #7156 is merged and its production backend is deployed. Read-only validation through the official PyAirbyte → Cloud → Sonar path confirmed the intended BigQuery project/database inventory, cross-dataset table discovery, and preserved default query context. Serving-release logs confirm the new version handled those checks.
Sonar #7159 is not required: this PR does not advertise its explicit IN DATABASE / IN SCHEMA syntax.
The Cloud MCP eval-harness follow-up remains separate and nonblocking, as agreed. Snowflake live validation remains untested because SQL passthrough is disabled in the authorized test setup; no configuration was changed.
Separate existing pagination-contract issue found during validation: the SQL tool exposes page_size, but it was ignored by the backend SQL request model. Backend response caps still apply. That follow-up is outside these PRs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
Summary
TL;DR: Teach agents that a connection’s loading schema can differ from the destination’s default query context, and expose those overrides in destination guidance.
Updates
execute_external_sql_query,describe_connector, and the existing connector-doc namespace inference path rather than introducing a second inference mechanism.Pairs with:
Validation gap
The single Cloud MCP eval run tested initial commit
57cc1b7: 0 passed, 125 startup errors, zero agent tool calls. Scenarios still require names such aslist_cloud_connections, but the server exposeslist_connections; the rename is already present in this PR’s RC merge base. The harness rejects its allowed-tool list before invoking any model. This provides no behavioral verdict on the change. No rerun was performed; follow-up transport/quoting fixes are covered by the local regressions below.Changes
destination_schemavalues.Deployment dependency
The
SHOW DATABASES/SHOW TABLESguidance describes the three-part behavior from Sonar #7156; deploy that backend change before releasing this companion. This does not advertise the explicit-context syntax from #7159.Test plan
uv run pytest tests/unit_tests/test_cloud_describe.py tests/unit_tests/test_mcp_cloud.py -q: 264 passed.uv run ruff check airbyte/_direct_connectors/connector_docs.py airbyte/mcp/cloud.py tests/unit_tests/test_cloud_describe.py: passed; formatter applied.uv run pyrefly check: 0 errors (73 suppressed).uv run poe check: passed (exit 0).Link to Devin session: https://app.devin.ai/sessions/c9b53cf95fa34cf699ed1779f3eb3b45
Open in Devin Desktop: https://app.devin.ai/desktop/session/c9b53cf95fa34cf699ed1779f3eb3b45?variant=devin
Requested by: Aaron ("AJ") Steers (@aaronsteers)