> ## Documentation Index > Fetch the complete documentation index at: https://docs.synq.io/llms.txt > Use this file to discover all available pages before exploring further. # RenderYaml > RenderYaml renders a ReconcilationSuite proto as a YAML config string. ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/agent/recon/v1/yaml/render openapi: 3.1.0 info: version: '1.0' title: SYNQ servers: - url: https://developer.synq.io - url: https://api.us.synq.io security: - bearerAuth: [] tags: - name: synq.issues.issues.v1.IssuesService description: IssuesService is a service for managing Issues. - name: synq.issues.v2.IssuesService description: IssuesService is a service for managing Issues. - name: synq.incidents.v1.IncidentsService description: IncidentsService is a service for managing Incidents. - name: synq.alerts.services.v1.AlertsService description: AlertsService provides operations for managing alert configurations. - name: synq.agent.recon.v1.YamlService description: >- YamlService provides stateless conversion between YAML config format and proto. This is useful for UI editors that need to display/edit suite configs as YAML. - name: synq.agent.recon.v1.SuiteDeploymentService description: |- SuiteDeploymentService is the platform plane of reconciliation. SuiteConfigService is the developer/authoring sandbox (edit, version, run ad-hoc with your own credentials — preview-only, no Entity, no Run, no Issue). A deployment is what SYNQ actually runs on the workspace's behalf: a frozen snapshot of a suite config, mapped to workspace-level SYNQ integrations, optionally scheduled or triggerable by API. Identity: every deployment has a stable deployment_id (UUIDv7) assigned on first promote. It survives re-promotes, schedule/mapping changes, and pause/resume. Downstream AssetCommand / RunCommand publication keys off deployment_id so Entity identity does not fragment on promote churn. - name: synq.agent.sre.v1.TriageService description: >- Service for managing issue triage operations, allowing LLM agents to conclude investigations and record evidence during the triage process. - name: synq.agent.sre.v1.LlmService description: Service for evaluating LLM requests and producing structured output. - name: synq.agent.sre.v1.FeatureRequestService description: >- FeatureRequestService allows MCP clients to submit feature requests when users encounter missing capabilities. This is a last-resort service — it should only be used when no existing tool can fulfill the user's request. - name: synq.integrations.v1.IntegrationsService description: |- IntegrationsService manages connections from Coalesce Quality to your data systems (warehouses, databases, and transformation tools). Concurrency: every integration carries an opaque `etag`. Read it from `GetIntegration` / `ListIntegrations`, then pass it back on `UpdateIntegration` / `DeleteIntegration` to ensure you modify the version you last saw. A stale etag is rejected with ABORTED (HTTP 409). Omit the etag for last-write-wins. Quota: each workspace has a limit on the number of integrations. Creating beyond the limit is rejected with RESOURCE_EXHAUSTED. Secrets: credential fields (passwords, tokens, keys) are write-only. They are masked (returned empty) on every read. On update, omit a secret to keep it, send a new value to rotate it, or send an explicit empty string to clear it (where the field is `optional`). - name: synq.auth.iam.v1.IamService - name: synq.monitors.predictions.v1.MonitorPredictionsService description: Access to anomaly detection model predictions and raw metric timeseries. - name: synq.monitors.info.v1.MonitorInfoService - name: synq.monitors.custom_monitors.v1.CustomMonitorsService - name: synq.monitors.history.v1.HistoryService - name: synq.monitors.automated_monitors.v1.DeploymentRulesService - name: synq.entities.executions.v2.EntityExecutionsService description: >- EntityExecutionsService provides read-only access to entity execution history. This service allows customers to retrieve information about all executions that happened on their entities, including execution status, timing, and messages. Use cases: - Retrieve execution history for specific entities - Filter executions by time range, status, or execution type - Get aggregated summaries of execution activity - Track execution trends and patterns - name: synq.datachecks.sqltests.v1.SqlTestsService description: SqlTestsService is a service for managing SqlTests. - name: synq.datachecks.v1.TriggerService description: TriggerService provides synchronous execution of datachecks on entities. - name: synq.datachecks.testsuggestions.v1.TestSuggestionsService - name: synq.extensions.atlan.provider.v1.AtlanProviderService - name: synq.extensions.atlan.integrations.v1.AtlanIntegrationService - name: synq.extensions.atlan.workflows.v1.AtlanWorkflowService - name: synq.platforms.v1.PlatformsService description: PlatformsService is a service for managing Platforms and Integrations. - name: synq.queries.v1.NLQueryService description: >- NLQueryService generates structured Query protos from natural language descriptions using an LLM. - name: synq.schedule.v1.ScheduleService description: ScheduleService provides schedule evaluation utilities. - name: synq.entities.executions.v1.EntityExecutionsService description: 'Deprecated: Use [synq.entities.custom.v1.EntityExecutionsService] instead' - name: synq.entities.status.v1.EntityIncidentsService description: EntityIncidentsService is the service which retrieves entity status. - name: synq.entities.status.v1.EntityIssuesService description: EntityIssuesService is the service which retrieves entity issues status. - name: synq.entities.orchestration.v1.OrchestrationService description: >- OrchestrationService provides information about orchestration relationships between entities. This includes relationships between Airflow tasks and transformation models (dbt, SQLMesh), as well as task-to-task dependencies. - name: synq.entities.coordinates.v1.DatabaseCoordinatesService description: >- DatabaseCoordinatesService is a service for getting database coordinates of Entities. - name: synq.entities.checks.v1.ChecksCategoriesService description: |- ChecksCategoriesService lets workspace admins set explicit category overrides on individual checks. An explicit category is the authoritative category for a check — it takes precedence over the categories computed by the workspace's categorisation rules. It is a public API so customers can manage check categories programmatically; the same service is also mounted on the internal API. The workspace and the acting identity are always taken from the request context, never from the payload. - name: synq.entities.sql_insights.v1.SqlInsightsService description: >- SqlInsightsService exposes analytical information about the SQL used across a workspace's entities. It answers questions such as "which SQL constructs are used in my warehouse, and how often" and "what SQL constructs does this specific entity use", without requiring the caller to re-parse any SQL. - name: synq.entities.custom.v1.RelationshipsService description: >- RelationshipsService allow management of relationships between entities. Relationships can be created, updated, and deleted between 2 custom entities, or between a custom entity and Coalesce Quality native entity.enum There is no option to create relationships between 2 Coalesce Quality native entities (dbt model, BI dashboard, etc.). - name: synq.entities.custom.v1.TypesService description: TypesService is a service for managing custom entity types. - name: synq.entities.custom.v1.GroupsService description: >- It eliminates the need to keep state on client side to remember which assets were already created and which should be deleted. The server will keep track of the current state of the group and client can always send the intended new state. The server will calculate the diff and entities that are no longer present in the group will be removed. Example: 1. group has entities A, B, C at time t1 2. client sends group with entities B, C, D at time t2 3. server will remove entity A from the system and update the current state of the group to B, C, D The service is designed to be idempotent and can be called multiple times with the same state without causing any side effects. - name: synq.entities.custom.v1.EntityExecutionsService - name: synq.entities.custom.v1.EntitiesService description: >- custom.EntitiesService is a service for managing custom entities. Entities can represent various data platform concepts such as services, consumers, applications or data pipelines that are not natively available in Coalesce Quality. Entities are identified by a unique identifier and can be created, updated, read and deleted. - name: synq.entities.custom.v1.FeaturesService - name: synq.entities.impact.v1.ImpactService - name: synq.entities.schemas.v1.SchemaMismatchesService description: >- SchemaMismatchesService provides access to schema drift information between data platform tables and their definitions (e.g., dbt models). - name: synq.entities.schemas.v1.SchemasService description: EntitiesService is a service for retriving any entity. - name: synq.entities.constraints.v1.TableConstraintsService description: >- TableConstraintsService provides access to table constraint and index information. - name: synq.entities.changes.v1.ChangesService description: >- ChangesService provides functionality to track and retrieve all types of changes to data entities. This unified service returns ALL change types for an entity: - Git commits: Changes to code files (dbt models, SQL files) tracked in version control - Schema changes: Database schema modifications (columns added/removed/changed) - SQL definition changes: View/materialized view definition updates detected by Coalesce Quality Changes are returned with structured metadata including: - For git commits: structured statistics (directories, file types, top changes) - For schema changes: detailed column-level diffs - For SQL changes: before/after SQL definitions Use cases: - "What changed in the last week for table X?" → Returns git commits, schema changes, SQL changes - "Show me all commits affecting this dbt model" → Returns git commits with lineage context - "What schema changes happened to this table?" → Returns schema changes detected by Coalesce Quality - name: synq.entities.lineage.v1.LineageService description: |- LineageService allows you to fetch: * Entity level lineage from a starting point of one or more entities. * Column Level lineage from a starting point of multiple columns of a single entity. - name: synq.entities.entities.v1.EntitiesService description: EntitiesService is a service for retriving any entity. - name: synq.entities.annotations.v1.AnnotationsService description: >- AnnotationsService provides operations for managing and querying entity annotations. Annotations are key-value pairs that can be attached to entities for categorization and filtering. - name: synq.entities.code.v1.CodeService description: >- CodeService is a service for retrieving code associated with entities in the system. It provides functionality to access and manage code artifacts such as SQL queries, Python scripts, dbt models, and other code configurations that are part of Coalesce Quality entities. - name: synq.entities.resolve.v1.IdentifierResolveService description: >- IdentifierResolveService resolves identifiers to their Coalesce Quality paths and identities. - name: synq.ingest.airflow.v1.AirflowLogsService - name: synq.ingest.cloudwatch.v1.CloudwatchService - name: synq.ingest.openlineage.v1.OpenlineageService - name: synq.ingest.dwh.v1.DwhService - name: synq.dataproducts.v1.DataproductsService description: DataproductsService can be used to manage data products. - name: synq.git.commits.v1.CommitsService paths: /api/agent/recon/v1/yaml/render: post: tags: - synq.agent.recon.v1.YamlService summary: RenderYaml description: RenderYaml renders a ReconcilationSuite proto as a YAML config string. operationId: synq.agent.recon.v1.YamlService.RenderYaml requestBody: content: application/json: schema: $ref: '#/components/schemas/synq.agent.recon.v1.RenderYamlRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/synq.agent.recon.v1.RenderYamlResponse' components: schemas: synq.agent.recon.v1.RenderYamlRequest: type: object properties: suite: $ref: '#/components/schemas/synq.agent.recon.v1.ReconcilationSuite' description: The suite configuration to render as YAML. title: RenderYamlRequest additionalProperties: false synq.agent.recon.v1.RenderYamlResponse: type: object properties: yaml: type: string description: The rendered YAML config string. title: RenderYamlResponse additionalProperties: false synq.agent.recon.v1.ReconcilationSuite: type: object properties: name: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ description: |- Short machine identifier for the suite. Unique machine identifier for the suite, used as the stable key for tracking runs over time. Alphanumerics, hyphens, and underscores. May be a UUID. title: type: string description: |- Human-readable title for the suite. Displayed in dashboards and reports. Defaults to name when not set. nullable: true description: type: string description: Optional longer description of the suite's purpose. nullable: true reconciliations: type: array items: $ref: '#/components/schemas/synq.agent.recon.v1.Reconcilation' minItems: 1 description: |- Reconciliation scenarios to execute. Each reconciliation compares data between a source and target dataset. setup: type: array items: $ref: '#/components/schemas/synq.agent.recon.v1.ConnectionQueries' description: |- Setup queries run once before all reconciliations begin. Use for creating temp tables, loading fixtures, or preparing the environment. Queries execute in order; all connections run sequentially. teardown: type: array items: $ref: '#/components/schemas/synq.agent.recon.v1.ConnectionQueries' description: |- Teardown queries run once after all reconciliations complete. Use for cleaning up temp tables or restoring state. teardownOnFailure: type: boolean description: >- Whether teardown runs even when reconciliations fail with infrastructure errors. When false (default), teardown is skipped on failure to preserve state for debugging. ignoreSetupErrors: type: boolean description: >- When true, logs setup query errors as warnings and continues execution instead of aborting the run. Useful when setup creates IF NOT EXISTS objects. variables: type: object additionalProperties: type: string title: value description: >- Template variables for query interpolation via {{variable_name}} syntax. Values can be literal strings or template expressions: - Literal: "2026-01-01" - Time expression: "{{today - 30d}}", "{{now - 2h}}" - Built-in: "{{now}}", "{{today}}", "{{window_start}}" Variables are resolved once at the start of the run and frozen. strictTimeReferences: type: boolean description: >- When true, time reference detection (e.g. NOW(), CURRENT_DATE, GETDATE() in queries) returns an error instead of a warning. Prevents non-deterministic queries that produce different results on each run. annotations: type: array items: $ref: '#/components/schemas/synq.entities.v1.Annotation' description: |- Suite-level annotations. Each annotation is a name with zero or more string values. Applied to the deployed suite asset and inherited by every reconciliation case under the suite. Merged with per-case annotations and deployment-level annotations at promote time — the final, deduplicated list is exposed on PromotedReconSuiteMetadata / PromotedReconCaseMetadata and surfaced to the rest of the SYNQ platform via EntityAnnotations. title: ReconcilationSuite required: - name additionalProperties: false description: |- ReconcilationSuite is the root configuration for a reconciliation suite. It defines template variables and one or more reconciliation scenarios that compare data between source and target databases. Database connections are configured separately and referenced by name. synq.agent.recon.v1.Reconcilation: type: object properties: name: type: string minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ description: >- Unique machine identifier within the suite. Alphanumerics, hyphens, and underscores. May be a UUID. title: type: string description: >- Human-readable title. Displayed in reports. Defaults to name when not set. nullable: true description: type: string description: >- Optional longer description explaining what this reconciliation validates. nullable: true source: $ref: '#/components/schemas/synq.agent.recon.v1.Dataset' description: >- Source dataset to compare from — the "expected" or "authoritative" side. target: $ref: '#/components/schemas/synq.agent.recon.v1.Dataset' description: >- Target dataset to compare against — the "actual" or "replicated" side. keyColumn: type: string description: >- Deprecated: use key_columns instead. Single primary key column used for ordering and segmentation during bisection. Retained for backward compatibility — existing single-key configs and stored audit logs keep working. When key_columns is set, this field is ignored. Readers should resolve the effective key via key_columns first, falling back to this. nullable: true deprecated: true keyColumns: type: array items: type: string description: >- Ordered list of key columns used for ordering and segmentation during bisection. Supports composite (multi-column) keys; the bisection orders and range-filters on the column tuple so the engine can prune via a matching primary key / index. A single-element list is equivalent to setting key_column. Required for ROW_CHECKSUM and ROW_COUNT modes (this or the deprecated key_column). Optional in AGGREGATE mode when group_columns provides the grouping key. mode: $ref: '#/components/schemas/synq.agent.recon.v1.ReconcilationMode' not: enum: - 0 description: Comparison mode controlling how source and target are compared. hashAlgorithm: $ref: '#/components/schemas/synq.agent.recon.v1.HashAlgorithm' description: |- Hash algorithm for row checksums in ROW_CHECKSUM mode. When unset, auto-negotiates the best common algorithm between the source and target database dialects. nullable: true columnMapping: type: array items: $ref: '#/components/schemas/synq.agent.recon.v1.ColumnMapping' description: |- Explicit column name mapping between source and target. Only columns with different names need mapping — identical names (or case-insensitive matches) are matched automatically. caseInsensitive: type: boolean description: >- When true, automatically matches columns differing only in letter case (e.g., user_id matches USER_ID). Defaults to true when not set. Set to false to require exact case matching. nullable: true bisection: $ref: '#/components/schemas/synq.agent.recon.v1.BisectionConfig' description: |- Bisection drill-down configuration for ROW_CHECKSUM mode. Controls how the key range is recursively split to locate mismatches. When not set, uses sensible defaults (factor=32, threshold=16384). nullable: true reporting: $ref: '#/components/schemas/synq.agent.recon.v1.ReportingConfig' description: >- Reporting output configuration controlling how much detail is included in the audit log for mismatched rows. nullable: true aggregate: $ref: '#/components/schemas/synq.agent.recon.v1.AggregateConfig' description: |- Aggregate comparison settings. Required when mode is AGGREGATE. Defines which measures to compare and tolerance thresholds. nullable: true errorHandling: $ref: '#/components/schemas/synq.agent.recon.v1.ErrorHandlingConfig' description: |- Error handling and retry configuration for database queries. Controls timeouts and retry behavior for transient failures. nullable: true window: $ref: '#/components/schemas/synq.agent.recon.v1.WindowConfig' description: |- Time window for incremental comparison. When set, automatically provides a {{window_start}} template variable for filtering queries to a recent time range. nullable: true setup: type: array items: $ref: '#/components/schemas/synq.agent.recon.v1.ConnectionQueries' description: |- Setup queries run before this specific reconciliation. Executes after suite-level setup but before data comparison. teardown: type: array items: $ref: '#/components/schemas/synq.agent.recon.v1.ConnectionQueries' description: Teardown queries run after this specific reconciliation completes. teardownOnFailure: type: boolean description: |- Whether teardown runs on failure for this reconciliation. When not set, inherits from suite-level teardown_on_failure. nullable: true ignoreSetupErrors: type: boolean description: |- When true, logs setup errors as warnings and continues. When not set, inherits from suite-level ignore_setup_errors. nullable: true cutoff: $ref: '#/components/schemas/synq.agent.recon.v1.CutoffConfig' description: |- Dynamic cutoff filter for sync reconciliation. Derives a watermark from actual data to exclude rows not yet synced. Applied as WHERE filter to both source and target queries at runtime. nullable: true annotations: type: array items: $ref: '#/components/schemas/synq.entities.v1.Annotation' description: |- Case-level annotations. Merged with suite-level annotations and deployment-level annotations at promote time, then exposed on the case asset (PromotedReconCaseMetadata). title: Reconcilation required: - name - source - target additionalProperties: false description: > Reconcilation defines a single reconciliation scenario comparing data between a source and target dataset. Each reconciliation runs independently and produces its own pass/mismatch/fail result. aggregate_config_required // aggregate config is required when mode is AGGREGATE key_column_and_key_columns_mutually_exclusive // set either key_column (single) or key_columns (composite), not both key_column_required_for_non_aggregate // key_column or key_columns is required unless mode is AGGREGATE synq.agent.recon.v1.ConnectionQueries: type: object properties: connection: type: string minLength: 1 description: |- Connection name to execute these queries on. Must reference a connection configured in the runner's connection map. queries: type: array items: type: string minItems: 1 minItems: 1 description: SQL queries to execute in order on this connection. title: ConnectionQueries required: - connection additionalProperties: false description: |- ConnectionQueries associates SQL queries with a specific connection. Used for setup and teardown blocks at both suite and reconciliation level. synq.entities.v1.Annotation: type: object properties: name: type: string maxLength: 50 minLength: 1 description: String key for the annotation. values: type: array items: type: string maxLength: 50 minLength: 1 maxItems: 20 maxItems: 20 description: Optional list of values that the annotation can carry. title: Annotation required: - name additionalProperties: false description: |- Annotations can be used to annotate any entity with a key:value pair. These annotations can be used for filtering and searching entities. synq.agent.recon.v1.Dataset: type: object allOf: - properties: connection: type: string title: connection minLength: 1 description: >- Name of the connection to use. Must reference a connection configured in the runner's connection map. asOf: type: string title: as_of description: >- Time-travel timestamp for snapshot queries (e.g., "2026-02-01 00:00:00"). When set, wraps the query with database-specific time-travel syntax: - Snowflake: AT(TIMESTAMP => '') - BigQuery: FOR SYSTEM_TIME AS OF TIMESTAMP '' - Databricks: TIMESTAMP AS OF '' Has no effect on databases that don't support time-travel. nullable: true - oneOf: - properties: query: type: string title: query description: |- Raw SQL query returning the dataset. Should be a SELECT or WITH (CTE) statement. Supports template variable interpolation via {{variable_name}} syntax. title: query required: - query - properties: table: $ref: '#/components/schemas/synq.agent.recon.v1.TableReference' title: table description: |- Table reference with optional column selection. Automatically generates a SELECT query from the table metadata. title: table required: - table title: Dataset required: - connection additionalProperties: false description: |- Dataset defines a source or target dataset for reconciliation. A dataset specifies which connection to use and how to select data — either via a raw SQL query or by referencing a table with optional column filtering. synq.agent.recon.v1.ReconcilationMode: type: string title: ReconcilationMode enum: - RECONCILATION_MODE_UNSPECIFIED - RECONCILATION_MODE_ROW_COUNT - RECONCILATION_MODE_ROW_CHECKSUM - RECONCILATION_MODE_AGGREGATE description: |- ReconcilationMode defines the comparison strategy for a reconciliation. Modes are ordered by depth of comparison: ROW_COUNT < ROW_CHECKSUM < AGGREGATE. synq.agent.recon.v1.HashAlgorithm: type: string title: HashAlgorithm enum: - HASH_ALGORITHM_UNSPECIFIED - HASH_ALGORITHM_MD5 - HASH_ALGORITHM_FARM_FINGERPRINT - HASH_ALGORITHM_XXHASH64 description: |- HashAlgorithm specifies the hash function used for row checksums in ROW_CHECKSUM mode. Different databases natively support different hash functions; choosing one supported by both sides avoids emulation overhead. synq.agent.recon.v1.ColumnMapping: type: object properties: source: type: string minLength: 1 description: Column name in the source dataset. target: type: string minLength: 1 description: Corresponding column name in the target dataset. title: ColumnMapping required: - source - target additionalProperties: false description: |- ColumnMapping maps a source column name to a target column name. Used when source and target use different naming conventions for the same data (e.g., snake_case vs SCREAMING_SNAKE_CASE, or completely different names). Only columns with different names need explicit mapping — columns with identical names (or case-insensitive matches when case_insensitive is true) are matched automatically. synq.agent.recon.v1.BisectionConfig: type: object properties: enabled: type: boolean description: |- Whether bisection drill-down is enabled. When false, only the quick-check (count + checksum) runs — mismatches are detected but not localized to specific rows. factor: type: integer maximum: 1024 minimum: 2 format: int32 description: |- Branching factor: how many segments each level is split into. Higher values find mismatches faster (fewer levels) but issue more queries per level. Default: 32. Typical range: 4–64. nullable: true threshold: type: integer minimum: 1 format: int32 description: >- Row count threshold: stop bisecting when a segment has fewer rows than this. Lower values find more precise mismatch locations but issue more queries. Default: 16384. Set to 1 to drill down to individual rows. nullable: true strategy: $ref: '#/components/schemas/synq.agent.recon.v1.SegmentationStrategy' description: Segmentation strategy for splitting key ranges. timeColumn: type: string description: |- Column for time-based partitioning. Required when strategy is TIME. Must be a timestamp, date, or datetime column in the dataset. nullable: true timeGranularity: $ref: '#/components/schemas/synq.agent.recon.v1.TimeGranularity' description: |- Granularity for time-based segmentation. Default: DAY. Controls the width of each time bucket when strategy is TIME. title: BisectionConfig additionalProperties: false description: > BisectionConfig controls the bisection drill-down algorithm that recursively splits the key range to locate individual mismatched rows. Only used in ROW_CHECKSUM mode. time_column_required_for_time_strategy // time_column is required when strategy is TIME synq.agent.recon.v1.ReportingConfig: type: object properties: level: $ref: '#/components/schemas/synq.agent.recon.v1.ReportingLevel' description: Output detail level for mismatched rows. sampleLimit: type: integer minimum: 1 format: int32 description: >- Maximum number of sample rows to include in output per mismatch segment. Limits the size of the audit log when there are many mismatches. When not set, all mismatched rows within the reporting level are included. nullable: true consentAcknowledged: type: boolean description: >- Explicit acknowledgment that detailed row data may be included in the audit log. Required when level is DETAILED to prevent accidental exposure of sensitive data. The caller must set this to true to confirm they understand the privacy implications. title: ReportingConfig additionalProperties: false description: > ReportingConfig controls the level of detail included in reconciliation output for mismatched rows. Higher detail levels reveal more data but may have privacy implications. consent_required_for_detailed // consent_acknowledged must be true when level is DETAILED synq.agent.recon.v1.AggregateConfig: type: object properties: measures: type: array items: $ref: '#/components/schemas/synq.agent.recon.v1.Measure' minItems: 1 description: |- Measures to compare between source and target. Each measure defines a column and one or more aggregate functions to apply. thresholds: $ref: '#/components/schemas/synq.agent.recon.v1.ThresholdConfig' description: |- Tolerance thresholds for aggregate comparisons. When not set, exact match is required for all measures. nullable: true groupColumns: type: array items: type: string description: |- Columns defining the drill-down hierarchy for aggregate comparison. Falls back to key_column if not set. Single column: flat GROUP BY comparison. group_columns: ["region"] → GROUP BY region Multiple columns: cumulative GROUP BY drill-down, pruning matched groups at each level to focus on divergent branches. group_columns: ["region", "city", "store"] → Level 0: GROUP BY region → Level 1: GROUP BY region, city (only for mismatched regions) → Level 2: GROUP BY region, city, store (only for mismatched cities) title: AggregateConfig additionalProperties: false description: |- AggregateConfig defines aggregate comparison settings. Used when mode is AGGREGATE to compare grouped measures between source and target. synq.agent.recon.v1.ErrorHandlingConfig: type: object properties: queryTimeout: $ref: '#/components/schemas/google.protobuf.Duration' description: >- Per-query timeout. When a query exceeds this duration, it is cancelled. Default: no per-query limit (only the global run timeout applies). nullable: true maxRetries: type: integer maximum: 10 minimum: 0 format: int32 description: |- Maximum retry attempts for transient query failures. The total number of attempts is max_retries + 1 (initial + retries). Default: 2. nullable: true retryInitialDelay: $ref: '#/components/schemas/google.protobuf.Duration' description: |- Initial backoff delay before the first retry. Subsequent retries multiply this by retry_backoff_factor. Default: 1s. nullable: true retryBackoffFactor: type: number minimum: 1 format: double description: |- Backoff multiplier applied after each retry. Delay for attempt N = retry_initial_delay * retry_backoff_factor^(N-1). Must be >= 1.0 to ensure delays don't decrease. Default: 2.0. nullable: true title: ErrorHandlingConfig additionalProperties: false description: >- ErrorHandlingConfig controls retry and timeout behavior for database queries. Applies to all queries within a reconciliation (setup, comparison, teardown). synq.agent.recon.v1.WindowConfig: type: object properties: column: type: string description: |- Column being windowed. Informational metadata for the audit trail — the actual filtering is done via the {{window_start}} variable in your query WHERE clause. nullable: true lookback: $ref: '#/components/schemas/google.protobuf.Duration' description: |- How far back to look from the current time. Defines the window as [now - lookback, now]. Examples: "336h" (14 days), "2h", "720h" (30 days). strategy: $ref: '#/components/schemas/synq.agent.recon.v1.WindowStrategy' description: Windowing strategy controlling how boundaries are computed. title: WindowConfig required: - lookback additionalProperties: false description: |- WindowConfig defines a time window for incremental comparison. When configured, automatically provides a {{window_start}} template variable that resolves to (current_time - lookback). Use this in query WHERE clauses to limit comparison to recent data. synq.agent.recon.v1.CutoffConfig: type: object properties: source: $ref: '#/components/schemas/synq.agent.recon.v1.CutoffSideConfig' description: |- Per-side watermark derivation config for source. When not set, derives from target only. nullable: true target: $ref: '#/components/schemas/synq.agent.recon.v1.CutoffSideConfig' description: |- Per-side watermark derivation config for target. When not set, derives from source only. nullable: true combine: $ref: '#/components/schemas/synq.agent.recon.v1.CutoffCombine' description: |- How to combine watermarks when both sides are configured. Default: MIN (use the smaller watermark for safety). Ignored when only one side has a watermark. truncate: $ref: '#/components/schemas/synq.agent.recon.v1.CutoffTruncate' description: |- Truncate the combined watermark to a time boundary. Example: HOUR truncates 08:47:12 to 08:00:00. Applied after combining, before offset. offset: $ref: '#/components/schemas/google.protobuf.Duration' description: |- Time offset applied after truncation. Negative durations subtract from the cutoff (safety buffer). Example: "-30m" shifts the cutoff 30 minutes earlier. nullable: true applySource: $ref: '#/components/schemas/synq.agent.recon.v1.CutoffApplyConfig' description: |- How to apply the cutoff as a WHERE filter on the source side. When not set, uses the source derivation column with <= operator. nullable: true applyTarget: $ref: '#/components/schemas/synq.agent.recon.v1.CutoffApplyConfig' description: |- How to apply the cutoff as a WHERE filter on the target side. When not set, uses the target derivation column with <= operator. nullable: true title: CutoffConfig additionalProperties: false description: |- CutoffConfig defines a dynamic cutoff filter for sync reconciliation. It derives a watermark value from the actual data (e.g., MAX(created_at)) to automatically exclude rows that haven't been synced yet. The cutoff is resolved at runtime before comparison queries run: 1. Derive watermark(s) from source and/or target via aggregate queries. 2. Combine them (default: MIN of both sides). 3. Optionally truncate to a time boundary and apply an offset. 4. Apply as WHERE filter to both source and target queries. synq.agent.recon.v1.TableReference: type: object properties: name: type: string minLength: 1 description: |- Table or view name (e.g., "orders", "fact_sales"). Required — this is the actual object name. columns: type: array items: type: string description: |- Explicit list of columns to include in the comparison. When set, only these columns are selected from the table. Mutually exclusive with exclude_columns. excludeColumns: type: array items: type: string description: |- Columns to exclude from the comparison. All columns except these are selected (resolved at runtime via table metadata). Useful for skipping volatile columns (e.g., updated_at, etl_batch_id). Mutually exclusive with columns. database: type: string description: |- Database/catalog name (e.g., "PROD_RAW", "my_project"). Maps to: Snowflake database, BigQuery project, Databricks catalog. nullable: true schema: type: string description: |- Schema/dataset name (e.g., "public", "analytics"). Maps to: Snowflake schema, BigQuery dataset, Databricks schema. nullable: true where: type: string description: |- Row filter — appended as WHERE clause to the generated SELECT. Example: "created_at >= '2024-01-01' AND status = 'active'" nullable: true title: TableReference required: - name additionalProperties: false description: | TableReference specifies a table and optional column filtering. Use this instead of a raw query when you want to compare all (or most) columns of a table without writing SQL. `name` is the table or view name (e.g., "orders", "fact_sales"). `database` and `schema` are optional namespace qualifiers. The actual SQL FQN is generated at runtime using the appropriate dialect quoting. columns_exclusive // columns and exclude_columns are mutually exclusive synq.agent.recon.v1.SegmentationStrategy: type: string title: SegmentationStrategy enum: - SEGMENTATION_STRATEGY_UNSPECIFIED - SEGMENTATION_STRATEGY_QUANTILE - SEGMENTATION_STRATEGY_HASH - SEGMENTATION_STRATEGY_TIME description: |- SegmentationStrategy defines how key ranges are split during bisection. The strategy affects both performance and privacy characteristics. synq.agent.recon.v1.TimeGranularity: type: string title: TimeGranularity enum: - TIME_GRANULARITY_UNSPECIFIED - TIME_GRANULARITY_HOUR - TIME_GRANULARITY_DAY - TIME_GRANULARITY_WEEK - TIME_GRANULARITY_MONTH - TIME_GRANULARITY_QUARTER - TIME_GRANULARITY_YEAR description: TimeGranularity defines the granularity for time-based segmentation. synq.agent.recon.v1.ReportingLevel: type: string title: ReportingLevel enum: - REPORTING_LEVEL_UNSPECIFIED - REPORTING_LEVEL_COUNT_ONLY - REPORTING_LEVEL_WITH_KEYS - REPORTING_LEVEL_DETAILED description: >- ReportingLevel controls how much detail is included in results for mismatched rows. Levels are ordered by increasing data exposure. synq.agent.recon.v1.Measure: type: object properties: column: type: string minLength: 1 description: >- Column name to aggregate. Must exist in both source and target datasets (after column mapping is applied). functions: type: array items: $ref: '#/components/schemas/synq.agent.recon.v1.AggregateFunction' minItems: 1 description: |- Aggregate functions to apply to this column. Multiple functions produce multiple measure comparisons from one column. title: Measure required: - column additionalProperties: false description: |- Measure defines a column and aggregate function(s) to compare between source and target datasets. A single measure with multiple functions expands into multiple comparisons (e.g., column="amount" functions=[SUM, AVG] produces "SUM(amount)" and "AVG(amount)"). synq.agent.recon.v1.ThresholdConfig: type: object properties: absolute: type: number minimum: 0 format: double description: |- Maximum allowed absolute difference per measure. When set, differences <= this value are considered within tolerance. Example: absolute = 0.01 accepts sub-cent rounding differences. nullable: true percentage: type: number minimum: 0 format: double description: |- Maximum allowed percentage difference per measure. Expressed as a decimal fraction: 0.1 = 10%, 0.01 = 1%. The formula used depends on percentage_mode. When set, differences <= this percentage are considered within tolerance. nullable: true percentageMode: $ref: '#/components/schemas/synq.agent.recon.v1.PercentageMode' description: |- Which percentage formula to use for threshold evaluation. Only relevant when percentage is set. perColumn: type: array items: $ref: '#/components/schemas/synq.agent.recon.v1.ColumnThresholdOverride' description: |- Per group_column level threshold overrides. Allows different tolerance for different levels of the drill-down hierarchy. For example, tighter thresholds at the city level than at the region level. Entries may themselves contain per_measure overrides for maximum specificity. perMeasure: type: array items: $ref: '#/components/schemas/synq.agent.recon.v1.MeasureThresholdOverride' description: |- Per measure threshold overrides. Allows different tolerance for different measures within the same reconciliation. For example, allow 1% tolerance for SUM(amount) but require exact COUNT match. title: ThresholdConfig additionalProperties: false description: |- ThresholdConfig defines tolerance thresholds for aggregate comparisons. A difference is reported as a mismatch only when it exceeds ALL configured thresholds (AND logic: both absolute AND percentage must be exceeded). Thresholds can be overridden at finer granularity: - per_column: override thresholds for a specific group_column drill-down level. - per_measure: override thresholds for a specific measure (e.g., "SUM(amount)"). - Nesting: per_column entries may contain per_measure overrides (most specific wins). When no thresholds are configured at any level, exact match is required. google.protobuf.Duration: type: string format: duration description: |- A Duration represents a signed, fixed-length span of time represented as a count of seconds and fractions of seconds at nanosecond resolution. It is independent of any calendar and concepts like "day" or "month". It is related to Timestamp in that the difference between two Timestamp values is a Duration and it can be added or subtracted from a Timestamp. Range is approximately +-10,000 years. # Examples Example 1: Compute Duration from two Timestamps in pseudo code. Timestamp start = ...; Timestamp end = ...; Duration duration = ...; duration.seconds = end.seconds - start.seconds; duration.nanos = end.nanos - start.nanos; if (duration.seconds < 0 && duration.nanos > 0) { duration.seconds += 1; duration.nanos -= 1000000000; } else if (duration.seconds > 0 && duration.nanos < 0) { duration.seconds -= 1; duration.nanos += 1000000000; } Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. Timestamp start = ...; Duration duration = ...; Timestamp end = ...; end.seconds = start.seconds + duration.seconds; end.nanos = start.nanos + duration.nanos; if (end.nanos < 0) { end.seconds -= 1; end.nanos += 1000000000; } else if (end.nanos >= 1000000000) { end.seconds += 1; end.nanos -= 1000000000; } Example 3: Compute Duration from datetime.timedelta in Python. td = datetime.timedelta(days=3, minutes=10) duration = Duration() duration.FromTimedelta(td) # JSON Mapping In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix "s" (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should be expressed in JSON format as "3.000000001s", and 3 seconds and 1 microsecond should be expressed in JSON format as "3.000001s". synq.agent.recon.v1.WindowStrategy: type: string title: WindowStrategy enum: - WINDOW_STRATEGY_UNSPECIFIED - WINDOW_STRATEGY_SLIDING - WINDOW_STRATEGY_FIXED description: WindowStrategy defines how the time window boundaries are computed. synq.agent.recon.v1.CutoffSideConfig: type: object properties: column: type: string description: >- Column to derive the watermark from (e.g., "created_at", "synced_at"). Required when query is not set. aggregate: $ref: '#/components/schemas/synq.agent.recon.v1.CutoffAggregate' description: |- Aggregate function to derive the watermark. Default: MAX. Only used when query is not set. query: type: string description: |- Custom SQL query for watermark derivation. Must return a single row with a "watermark" column. When not set, auto-generated from the dataset at runtime. After resolution, this field is populated with the actual query that was executed. nullable: true title: CutoffSideConfig additionalProperties: false description: >- CutoffSideConfig configures watermark derivation for one side (source or target). There are two modes: 1. Column + aggregate (default): auto-generates a watermark query from the dataset. For table-based datasets, queries the table directly (the column does NOT need to be in the reconciliation column list). For query-based datasets, wraps the query as a subquery (the column MUST be in the query's SELECT list). 2. Custom query: provide a SQL query that returns a single row with a "watermark" column. Use this when the auto-generated query doesn't work (e.g., complex joins, custom logic). After resolution at runtime, the `query` field is always populated with the actual SQL that was executed, regardless of which mode was used. This ensures the audit log captures the exact query for reproducibility. synq.agent.recon.v1.CutoffCombine: type: string title: CutoffCombine enum: - CUTOFF_COMBINE_UNSPECIFIED - CUTOFF_COMBINE_MIN - CUTOFF_COMBINE_MAX - CUTOFF_COMBINE_SOURCE - CUTOFF_COMBINE_TARGET description: CutoffCombine defines how to combine watermarks from source and target. synq.agent.recon.v1.CutoffTruncate: type: string title: CutoffTruncate enum: - CUTOFF_TRUNCATE_UNSPECIFIED - CUTOFF_TRUNCATE_HOUR - CUTOFF_TRUNCATE_DAY - CUTOFF_TRUNCATE_WEEK - CUTOFF_TRUNCATE_MONTH - CUTOFF_TRUNCATE_QUARTER - CUTOFF_TRUNCATE_YEAR description: CutoffTruncate defines time truncation for the cutoff value. synq.agent.recon.v1.CutoffApplyConfig: type: object properties: column: type: string description: >- Column to filter on. When not set, uses the derivation column from that side. nullable: true operator: type: string description: 'Comparison operator. Default: "<=".' nullable: true title: CutoffApplyConfig additionalProperties: false description: >- CutoffApplyConfig controls how the resolved cutoff value is applied as a WHERE filter. synq.agent.recon.v1.AggregateFunction: type: string title: AggregateFunction enum: - AGGREGATE_FUNCTION_UNSPECIFIED - AGGREGATE_FUNCTION_SUM - AGGREGATE_FUNCTION_COUNT - AGGREGATE_FUNCTION_AVG - AGGREGATE_FUNCTION_MIN - AGGREGATE_FUNCTION_MAX description: |- AggregateFunction defines the supported SQL aggregate functions for measure comparisons in aggregate reconciliation mode. synq.agent.recon.v1.PercentageMode: type: string title: PercentageMode enum: - PERCENTAGE_MODE_UNSPECIFIED - PERCENTAGE_MODE_SOURCE - PERCENTAGE_MODE_TARGET - PERCENTAGE_MODE_SYMMETRIC description: >- PercentageMode controls which percentage formula is used for threshold comparison. The choice affects how "big" a difference appears when source and target values differ in magnitude. synq.agent.recon.v1.ColumnThresholdOverride: type: object properties: column: type: string minLength: 1 description: |- Group column name this override applies to. Must match one of the group_columns in the AggregateConfig. thresholds: $ref: '#/components/schemas/synq.agent.recon.v1.ThresholdConfig' description: |- Threshold overrides for this group column level. Values here override the parent ThresholdConfig for reconciliation groups at this drill-down level. May include per_measure for further specificity. title: ColumnThresholdOverride required: - column - thresholds additionalProperties: false description: |- ColumnThresholdOverride associates threshold overrides with a specific group_column level in the aggregate drill-down hierarchy. synq.agent.recon.v1.MeasureThresholdOverride: type: object properties: function: $ref: '#/components/schemas/synq.agent.recon.v1.AggregateFunction' not: enum: - 0 description: Aggregate function this override applies to. column: type: string minLength: 1 description: |- Column name this override applies to. Together with function, forms the measure key (e.g., SUM + "amount" = "SUM(amount)"). thresholds: $ref: '#/components/schemas/synq.agent.recon.v1.ThresholdConfig' description: |- Threshold overrides for this specific measure. Values here override the parent ThresholdConfig (and any per_column override) for this measure only. title: MeasureThresholdOverride required: - column - thresholds additionalProperties: false description: |- MeasureThresholdOverride associates threshold overrides with a specific measure (aggregate function + column combination). synq.agent.recon.v1.CutoffAggregate: type: string title: CutoffAggregate enum: - CUTOFF_AGGREGATE_UNSPECIFIED - CUTOFF_AGGREGATE_MAX - CUTOFF_AGGREGATE_MIN description: CutoffAggregate defines the aggregate function for watermark derivation. securitySchemes: bearerAuth: type: http scheme: bearer ````