Aller au contenu principal

Source analysis

Every source is analyzed before it can become useful context. The public result is discriminated by source kind; credentials, database sample rows, and unrestricted API responses never cross the management boundary.

Database flow​

Platform database setup and MCP reuse the existing datasource-onboarding Durable Object for PostgreSQL, MySQL, BigQuery, and ClickHouse:

  1. Validate the connection and its Project scope.
  2. Inspect schema, columns, keys, and relationships.
  3. Read only bounded samples for semantic analysis.
  4. Build the datasource profile and query guide.
  5. Return follow-up questions only when business meaning is ambiguous.
  6. Require explicit confirmation before activation.

MCP uses structured tools, not free-form confirmation parsing:

create_tunnel_source
start_source_analysis
get_source_analysis
continue_source_analysis { answer: "..." }
continue_source_analysis { confirm: true }

get_source_analysis removes all sampled rows and rechecks the current token's datasource allowlist on every read and continuation. MCP can relay an administrator's answer, but cannot answer with hidden samples or widen the caller's permissions.

The database analysis tools require datasources.write. OpenAPI registration additionally requires embed.datasources.write; partner authoring keys include both while remaining fixed to one Project and Environment.

OpenAPI flow​

OpenAPI authoring is deterministic and non-interactive:

  1. Preflight a same-origin bounded JSON or YAML contract.
  2. Canonicalize and hash the document.
  3. Inspect request and response schemas.
  4. Return eligible side-effect-free operations and diagnostics.
  5. Review policy parameter mappings and result fields.
  6. Register an immutable source revision and bind it to a Data Context (Partner Analytical Pack in the API).

OpenAPI does not run inside the Durable Object. Platform exposes Analyze contract before registration, @dataira/node exposes preflightOpenApi(), and MCP start_source_analysis returns the static registered-source analysis with interactive: false and an empty questions array.

Authoring never invokes a live partner operation. This avoids inventing an end-user identity or touching customer data. Runtime calls happen only after publication with a real policy-bound end user, exact source generation, budgets, and a versioned receipt.

Shared guarantees​

  • Tenant, Project, Environment, datasource, actor, and API-key scope are checked server-side.
  • Database and API credentials remain encrypted server-side.
  • A source catalog is only an upper bound; end-user allowlists and row/column policy can narrow it.
  • Analysis cannot publish an Analytical Pack or activate a source by itself.
  • Schema or contract drift advances authorization generation and invalidates stale context.

Direct database creation through the current backend SDK returns a pending connection. Use the guided Platform flow or MCP tunnel analysis for the interactive analysis lifecycle until the SDK exposes the same session contract.