Datafold Data diffs API

openapi: 3.2.0
info:
  contact:
    email: support@datafold.com
    name: API Support
  description: "The Datafold API reference is a guide to our available endpoints and authentication methods.\nIf you're just getting started with Datafold, we recommend first checking out our [documentation](https://docs.datafold.com).\n\n:::info\n  To use the Datafold API, you should first create a Datafold API Key,\n  which should be stored as a local environment variable named DATAFOLD_API_KEY.\n  This can be set in your Datafold Cloud's Settings under the Account page.\n:::"
  title: Datafold Audit Logs Data diffs API
  version: latest
servers:
- description: Default server
  url: https://app.datafold.com
security:
- ApiKeyAuth: []
tags:
- name: Data diffs
paths:
  /api/v1/datadiffs:
    get:
      description: 'All fields support multiple items, using just comma delimiter

        Date fields also support ranges using the following syntax:


        - ``<DATETIME`` = before DATETIME

        - ``>DATETIME`` = after DATETIME

        - ``DATETIME`` = between DATETIME and DATETIME + 1 MINUTE

        - ``DATE`` = start of that DATE until DATE + 1 DAY

        - ``DATETIME1<<DATETIME2`` = between DATETIME1 and DATETIME2

        - ``DATE1<<DATE2`` = between DATE1 and DATE2'
      operationId: list_datadiffs_api_v1_datadiffs_get
      parameters:
      - in: query
        name: page
        required: false
        schema:
          default: 1
          title: Page
          type: integer
      - in: query
        name: page_size
        required: false
        schema:
          default: 100
          title: Page Size
          type: integer
      - in: query
        name: sort_order
        required: false
        schema:
          $ref: '#/components/schemas/ApiSortOrder'
          default: asc
      - in: query
        name: order_by
        required: false
        schema:
          $ref: '#/components/schemas/ApiSortFilters'
          default: id
      - in: query
        name: accessible_only
        required: false
        schema:
          default: false
          title: Accessible Only
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiDataDiffPage'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List data diffs
      tags:
      - Data diffs
    post:
      description: 'Launches a new data diff to compare two datasets (tables or queries).


        A data diff identifies differences between two datasets by comparing:

        - Row-level changes (added, removed, modified rows)

        - Schema differences

        - Column-level statistics


        The diff runs asynchronously. Use the returned diff ID to poll for status and retrieve results.'
      operationId: create_datadiff_api_v1_datadiffs_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiDataDiffData'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiDataDiffFull'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Create a data diff
      tags:
      - Data diffs
  /api/v1/datadiffs/{datadiff_id}:
    get:
      operationId: get_datadiff_api_v1_datadiffs__datadiff_id__get
      parameters:
      - in: path
        name: datadiff_id
        required: true
        schema:
          title: Data diff id
          type: integer
      - in: query
        name: poll
        required: false
        schema:
          title: Poll
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiDataDiffWithProgressState'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get a data diff
      tags:
      - Data diffs
    patch:
      operationId: update_datadiff_api_v1_datadiffs__datadiff_id__patch
      parameters:
      - in: path
        name: datadiff_id
        required: true
        schema:
          title: Data diff id
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Body_update_datadiff_api_v1_datadiffs__datadiff_id__patch'
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Update a data diff
      tags:
      - Data diffs
  /api/v1/datadiffs/{datadiff_id}/cancel:
    post:
      description: 'Cancels a data diff that is currently queued or running.


        This operation stops the diff execution and marks it as cancelled. If the diff has already

        completed or been cancelled, this operation has no effect and returns the current status.


        Use this to stop long-running diffs that are no longer needed or were started with incorrect parameters.'
      operationId: cancel_diff_api_v1_datadiffs__datadiff_id__cancel_post
      parameters:
      - in: path
        name: datadiff_id
        required: true
        schema:
          title: Data diff id
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiDataDiffCancelled'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Cancel a running data diff
      tags:
      - Data diffs
  /api/v1/datadiffs/{datadiff_id}/summary:
    get:
      description: 'Retrieves a comprehensive, human-readable summary of a completed data diff.


        This endpoint provides the most useful information for understanding diff results:

        - Overall status and result (success/failure)

        - Human-readable feedback explaining the differences found

        - Key statistics (row counts, differences, match rates)

        - Configuration details (tables compared, primary keys used)

        - Error messages if the diff failed


        Use this after a diff completes to get actionable insights. For diffs still running,

        check status with get_datadiff first.'
      operationId: get_diff_summary_api_v1_datadiffs__datadiff_id__summary_get
      parameters:
      - in: path
        name: datadiff_id
        required: true
        schema:
          title: Data diff id
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiDataDiffSummary'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get a human-readable summary of a DataDiff comparison
      tags:
      - Data diffs
  /api/v1/datadiffs/{datadiff_id}/summary_results:
    get:
      operationId: get_diff_summary_v1_api_v1_datadiffs__datadiff_id__summary_results_get
      parameters:
      - in: path
        name: datadiff_id
        required: true
        schema:
          title: Data diff id
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ApiDataDiffSummaryForDone'
                - $ref: '#/components/schemas/ApiCrossDataDiffSummaryForDone'
                - $ref: '#/components/schemas/ApiDataDiffSummaryForFailed'
                - $ref: '#/components/schemas/ApiDataDiffSummaryForRunning'
                - $ref: '#/components/schemas/InternalApiDataDiffDependencies'
                title: Response Get Diff Summary V1 Api V1 Datadiffs  Datadiff Id  Summary Results Get
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get a data diff summary
      tags:
      - Data diffs
components:
  schemas:
    ApiDataDiffSummaryForDone:
      properties:
        dependencies:
          items:
            $ref: '#/components/schemas/ApiCIDependency'
          title: Dependencies
          type: array
        exclusives_profile:
          anyOf:
          - $ref: '#/components/schemas/ApiExclusiveRowsProfile'
          - type: 'null'
          description: Distribution statistics for exclusive rows (rows that exist in one table but not the other). Includes histograms and enum distributions for primary key columns. Only available for diffs computed after October 2025.
        materialized_results:
          $ref: '#/components/schemas/ApiMaterializedResults'
          description: Results of the diff, materialized into tables.
        pks:
          $ref: '#/components/schemas/ApiDataDiffSummaryPKs'
        schema:
          $ref: '#/components/schemas/ApiDataDiffSummarySchema'
        status:
          enum:
          - done
          - success
          title: Status
          type: string
        values:
          anyOf:
          - $ref: '#/components/schemas/ApiDataDiffSummaryValues'
          - type: 'null'
      required:
      - status
      - pks
      - dependencies
      - schema
      - materialized_results
      title: ApiDataDiffSummaryForDone
      type: object
    ToleranceModeEnum:
      enum:
      - absolute
      - relative
      title: ToleranceModeEnum
      type: string
    ApiDataDiffSummaryForFailed:
      properties:
        error:
          anyOf:
          - $ref: '#/components/schemas/ApiDataDiffError'
          - additionalProperties: true
            type: object
          title: Error
        status:
          const: failed
          title: Status
          type: string
      required:
      - status
      - error
      title: ApiDataDiffSummaryForFailed
      type: object
    InternalApiDataDiffDependencies:
      properties:
        dependencies:
          items:
            $ref: '#/components/schemas/ApiCIDependency'
          title: Dependencies
          type: array
        status:
          enum:
          - done
          - success
          title: Status
          type: string
      required:
      - status
      - dependencies
      title: InternalApiDataDiffDependencies
      type: object
    ApiDataDiffError:
      properties:
        error_type:
          title: Error Type
          type: string
        error_value:
          title: Error Value
          type: string
        is_retryable:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Retryable
      required:
      - error_type
      - error_value
      title: ApiDataDiffError
      type: object
    ApiDataDiffSummaryValues:
      properties:
        columns_diff_stats:
          items:
            $ref: '#/components/schemas/ApiColumnDiffStat'
          title: Columns Diff Stats
          type: array
        columns_with_differences:
          title: Columns With Differences
          type: integer
        compared_columns:
          title: Compared Columns
          type: integer
        rows_with_differences:
          title: Rows With Differences
          type: integer
        total_rows:
          title: Total Rows
          type: integer
        total_values:
          title: Total Values
          type: integer
        values_with_differences:
          title: Values With Differences
          type: integer
      required:
      - total_rows
      - rows_with_differences
      - total_values
      - values_with_differences
      - compared_columns
      - columns_with_differences
      - columns_diff_stats
      title: ApiDataDiffSummaryValues
      type: object
    DiffKind:
      enum:
      - in_db
      - cross_db
      title: DiffKind
      type: string
    ExcelFileOptions:
      properties:
        file_type:
          const: excel
          default: excel
          title: File Type
          type: string
        sheet:
          anyOf:
          - type: string
          - type: 'null'
          title: Sheet
        skip_head_rows:
          anyOf:
          - type: integer
          - type: 'null'
          title: Skip Head Rows
        skip_tail_rows:
          anyOf:
          - type: integer
          - type: 'null'
          title: Skip Tail Rows
      title: ExcelFileOptions
      type: object
    ApiSortOrder:
      enum:
      - asc
      - desc
      title: ApiSortOrder
      type: string
    ApiEstimatedIntValue:
      properties:
        confidence:
          description: Confidence level (e.g., 0.95)
          title: Confidence
          type: number
        estimate:
          description: Estimated value for full dataset
          title: Estimate
          type: integer
        interval:
          $ref: '#/components/schemas/ApiEstimatedIntInterval'
          description: Confidence interval bounds
        value:
          description: Observed value in sample
          title: Value
          type: integer
      required:
      - value
      - estimate
      - confidence
      - interval
      title: ApiEstimatedIntValue
      type: object
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    ApiEstimatedIntInterval:
      properties:
        max:
          title: Max
          type: integer
        min:
          title: Min
          type: integer
      required:
      - min
      - max
      title: ApiEstimatedIntInterval
      type: object
    TimeAggregateEnum:
      enum:
      - minute
      - hour
      - day
      - week
      - month
      - year
      title: TimeAggregateEnum
      type: string
    JobStatus:
      enum:
      - needs_confirmation
      - needs_authentication
      - waiting
      - queued
      - processing
      - done
      - failed
      - cancelled
      title: JobStatus
      type: string
    ApiDataDiffSummarySchema:
      properties:
        column_counts:
          maxItems: 2
          minItems: 2
          prefixItems:
          - type: integer
          - type: integer
          title: Column Counts
          type: array
        column_reorders:
          title: Column Reorders
          type: integer
        column_type_differs:
          items:
            type: string
          title: Column Type Differs
          type: array
        column_type_mismatches:
          title: Column Type Mismatches
          type: integer
        columns_mismatched:
          maxItems: 2
          minItems: 2
          prefixItems:
          - type: integer
          - type: integer
          title: Columns Mismatched
          type: array
        exclusive_columns:
          items:
            items:
              type: string
            type: array
          title: Exclusive Columns
          type: array
      required:
      - columns_mismatched
      - column_type_mismatches
      - column_reorders
      - column_counts
      - column_type_differs
      - exclusive_columns
      title: ApiDataDiffSummarySchema
      type: object
    ApiCIDependency:
      properties:
        data_source_id:
          title: Data Source Id
          type: integer
        data_source_type:
          title: Data Source Type
          type: string
        item_type:
          title: Item Type
          type: string
        name:
          title: Name
          type: string
        path:
          items:
            type: string
          title: Path
          type: array
        popularity:
          anyOf:
          - type: integer
          - type: 'null'
          title: Popularity
        primary_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Primary Key
        query_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Query Type
        raw_sql:
          anyOf:
          - type: string
          - type: 'null'
          title: Raw Sql
        remote_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Remote Id
        table_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Table Name
        uid:
          title: Uid
          type: string
      required:
      - uid
      - item_type
      - name
      - path
      - data_source_id
      - data_source_type
      title: ApiCIDependency
      type: object
    ApiMaterializedResult:
      properties:
        data_source_id:
          description: Id of the DataSource where the table is located
          title: Data Source Id
          type: integer
        is_sampled:
          description: If sampling was applied
          title: Is Sampled
          type: boolean
        path:
          description: Path segments of the table
          items:
            type: string
          title: Path
          type: array
      required:
      - data_source_id
      - path
      - is_sampled
      title: ApiMaterializedResult
      type: object
    ApiColumnRule:
      properties:
        column:
          anyOf:
          - minLength: 1
            type: string
          - type: 'null'
          description: Column name the rule applies to. When column remapping is enabled, this refers to the dataset-A (canonical) column name — the same name the comparator operates on after remapping. Mutually exclusive with `type`. Exactly one of `column` or `type` must be set.
          title: Column
        equal_if:
          description: SQL boolean expression OR-ed into the value comparator for the matching column(s). Use {a} and {b} as placeholders for the side-A and side-B column references. Multiple rules matching the same column are all OR-ed together.
          title: Equal If
          type: string
        type:
          anyOf:
          - $ref: '#/components/schemas/DatatypeName'
          - type: 'null'
          description: Type-based selector — matches all columns whose Datatype.typename equals this value. The rule is applied to every column of that type after data lands in DuckDB post-fetch. Mutually exclusive with `column`.
      required:
      - equal_if
      title: ApiColumnRule
      type: object
    ApiColumnDiffStat:
      properties:
        column_name:
          title: Column Name
          type: string
        match:
          description: Percentage of cells that matched (0-100)
          title: Match
          type: number
        values_different:
          description: Count of different cells observed in the sample
          title: Values Different
          type: integer
        values_different_estimate:
          anyOf:
          - $ref: '#/components/schemas/ApiEstimatedIntValue'
          - type: 'null'
          description: Statistical estimate of differences for the full dataset. Only present when sampling was applied. Includes observed value, extrapolated estimate, confidence level, and confidence interval bounds.
      required:
      - column_name
      - match
      - values_different
      title: ApiColumnDiffStat
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    MonitorRunState:
      enum:
      - ok
      - alert
      - error
      - learning
      - checking
      - created
      - skipped
      - cancelled
      - queued
      title: MonitorRunState
      type: string
    ApiDataDiffFull:
      properties:
        affected_columns:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Affected Columns
        algorithm:
          anyOf:
          - $ref: '#/components/schemas/DiffAlgorithm'
          - type: 'null'
          description: 'Diff algorithm. ''join'' for same-database diffs, ''fetch_and_join'' for cross-database or file diffs. Auto-selected if omitted: ''join'' when both data sources are the same, ''fetch_and_join'' otherwise.'
        archived:
          default: false
          title: Archived
          type: boolean
        bisection_factor:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bisection Factor
        bisection_threshold:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bisection Threshold
        ci_base_branch:
          anyOf:
          - type: string
          - type: 'null'
          title: Ci Base Branch
        ci_pr_branch:
          anyOf:
          - type: string
          - type: 'null'
          title: Ci Pr Branch
        ci_pr_num:
          anyOf:
          - type: integer
          - type: 'null'
          title: Ci Pr Num
        ci_pr_sha:
          anyOf:
          - type: string
          - type: 'null'
          title: Ci Pr Sha
        ci_pr_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Ci Pr Url
        ci_pr_user_display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Ci Pr User Display Name
        ci_pr_user_email:
          anyOf:
          - type: string
          - type: 'null'
          title: Ci Pr User Email
        ci_pr_user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Ci Pr User Id
        ci_pr_username:
          anyOf:
          - type: string
          - type: 'null'
          title: Ci Pr Username
        ci_run_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Ci Run Id
        ci_sha_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Ci Sha Url
        column_mapping:
          anyOf:
          - items:
              maxItems: 2
              minItems: 2
              prefixItems:
              - type: string
              - type: string
              type: array
            type: array
          - type: 'null'
          description: Map columns with different names between datasets. List of [column_in_A, column_in_B] pairs.
          title: Column Mapping
        column_rules:
          anyOf:
          - items:
              $ref: '#/components/schemas/ApiColumnRule'
            type: array
          - type: 'null'
          description: Extra equality clauses that extend the in-memory diff value comparator. Useful for treating specific value pairs (e.g. legacy sentinels vs NULL) as non-differences. See `ApiColumnRule` for entry shape.
          title: Column Rules
        columns_to_compare:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          description: Columns to compare between datasets. If set, only these columns are diffed (primary key columns are always included). Column names must match the dataset schema.
          title: Columns To Compare
        compare_duplicates:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Compare rows with duplicate primary keys. Defaults to true.
          title: Compare Duplicates
        created_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Created At
        data_app_metadata:
          anyOf:
          - $ref: '#/components/schemas/TDataDiffDataAppMetadata'
          - type: 'null'
        data_app_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Data App Type
        data_source1_id:
          description: ID of the first data source (Dataset A).
          title: Data Source1 Id
          type: integer
        data_source1_session_parameters:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          description: 'Snowflake session parameters for Dataset A, e.g. {"QUERY_TAG": "datadiff", "WAREHOUSE": "COMPUTE_WH"}.'
          title: Data Source1 Session Parameters
        data_source2_id:
          description: ID of the second data source (Dataset B). Can be the same as data_source1_id.
          title: Data Source2 Id
          type: integer
        data_source2_session_parameters:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          description: Snowflake session parameters for Dataset B.
          title: Data Source2 Session Parameters
        datetime_tolerance:
          anyOf:
          - type: integer
          - type: 'null'
          description: Datetime precision for comparison. 0=seconds, 1=tenths, 2=hundredths, 3=milliseconds, 4=tenth-ms, 5=hundredth-ms, 6=microseconds.
          title: Datetime Tolerance
        diff_stats:
          anyOf:
          - $ref: '#/components/schemas/DiffStats'
          - type: 'null'
        diff_tolerance:
          anyOf:
          - type: number
          - type: 'null'
          description: 'Default tolerance for float comparisons. In absolute mode: values within this distance are equal. In relative mode: fraction of difference allowed.'
          title: Diff Tolerance
        diff_tolerances_per_column:
          anyOf:
          - items:
              $ref: '#/components/schemas/ColumnTolerance'
            type: array
          - type: 'null'
          description: 'Per-column tolerance overrides. Each entry: {column_name, tolerance_value (>= 0), tolerance_mode: ''absolute''|''relative''}.'
          title: Diff Tolerances Per Column
        done:
          anyOf:
          - type: boolean
          - type: 'null'
          default: false
          title: Done
        download_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Download Limit
        exclude_columns:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          description: Columns to exclude from comparison. Ignored if include_columns is set.
          title: Exclude Columns
        execute_as_user:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Execute As User
        file1:
          anyOf:
          - format: uri
            minLength: 1
            type: string
          - type: 'null'
          description: File URL for Dataset A (s3://, gs://, abfss://, https://). Mutually exclusive with table1 and query1. Requires file1_options.
          title: File1
        file1_options:
          anyOf:
          - discriminator:
              mapping:
                csv: '#/components/schemas/CSVFileOptions'
                excel: '#/components/schemas/ExcelFileOptions'
                parquet: '#/components/schemas/ParquetFileOptions'
              propertyName: file_type
            oneOf:
            - $ref: '#/components/schemas/CSVFileOptions'
            - $ref: '#/components/schemas/ExcelFileOptions'
            - $ref: '#/components/schemas/ParquetFileOptions'
          - type: 'null'
          description: File format options for file1 (file_type, delimiter, sheet, skip rows).
          title: File1 Options
        file2:
          anyOf:
          - format: uri
            minLength: 1
            type: string
          - type: 'null'
          description: File URL for Dataset B (s3://, gs://, abfss://, https://). Mutually exclusive with table2 and query2. Requires file2_options.
          title: File2
        file2_options:
          anyOf:
          - discriminator:
              mapping:
                csv: '#/components/schemas/CSVFileOptions'
                excel: '#/components/schemas/ExcelFileOptions'
                parquet: '#/components/schemas/ParquetFileOptions'
              propertyName: file_type
            oneOf:
            - $ref: '#/components/schemas/CSVFileOptions'
            - $ref: '#/components/schemas/ExcelFileOptions'
            - $ref: '#/components/schemas/ParquetFileOptions'
          - type: 'null'
          description: File format options for file2 (file_type, delimiter, sheet, skip rows).
          title: File2 Options
        filter1:
          anyOf:
          - type: string
          - type: 'null'
          description: SQL WHERE clause for Dataset A (omit the WHERE keyword), e.g. 'status = 1'.
          title: Filter1
        filter2:
          anyOf:
          - type: string
          - type: 'null'
          description: SQL WHERE clause for Dataset B (omit the WHERE keyword), e.g. 'status = 1'.
          title: Filter2
        finished_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Finished At
        id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Id
        include_columns:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          description: Explicit list of columns to compare. If set, only these columns are diffed.
          title: Include Columns
        infer_pk:
          default: false
          description: 'Infer primary key columns automatically before running the diff. When true, pk_columns may be omitted; the inferred PK is stored back on the diff. Supported configurations: in-db diffs (all input types); cross-db diffs with query inputs on both sides (PK is inferred inside DuckDB after fetch). Not supported: cross-db with table inputs, or any file-based diff — use POST /api/v1/data_sources/{id}/guess_pk and pass pk_columns explicitly. For in-db query inputs, materialization is auto-forced.'
          title: Infer Pk
          type: boolean
        infer_pk_avoid_names:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          description: Column names to skip during PK inference. Matched case-insensitively against actual column names (exact match, no glob/regex). Requires infer_pk=true and pk_columns empty; rejected with 422 otherwise.
          title: Infer Pk Avoid Names
        infer_pk_avoid_types:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          description: Extra column types to skip during PK inference, on top of the built-in defaults (float, timestamp, array, boolean, binary, unsupported). Use canonical type names (e.g. 'integer', 'text') or 'db:<RAW_TYPE>' to target a raw warehouse type (e.g. 'db:JSONB'). Requires infer_pk=true and pk_columns empty; rejected with 422 otherwise.
          title: Infer Pk Avoid Types
        kind:
          $ref: '#/components/schemas/DiffKind'
        materialization_destination_id:
          anyOf:
          - type: integer
          - type: 'null'
          description: Data source ID where materialized diff results are stored.
          title: Materialization Destination Id
        materialize_dataset1:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Materialize Dataset A before diffing. Improves speed for heavy queries, filtered non-indexed columns, or transformed primary keys.
          title: Materialize Dataset1
        materialize_dataset2:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Materialize Dataset B

# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/datafold/refs/heads/main/openapi/datafold-data-diffs-api-openapi.yml