> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datachecks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Comparison

> Create a new comparison between a source and target dataset.

<ParamField header="Authorization" type="string" required>
  Bearer token. Format: `Bearer <api-key>`
</ParamField>

<ParamField header="Workspace-Id" type="string" required>
  Your workspace UUID.
</ParamField>

<ParamField query="create_only" type="boolean" default="false">
  If `true`, creates the comparison without triggering execution.
</ParamField>

<ParamField body="name" type="string" required>
  Display name for the comparison.
</ParamField>

<ParamField body="source_datasource_id" type="string" required>
  UUID of the source data source.
</ParamField>

<ParamField body="target_datasource_id" type="string" required>
  UUID of the target data source.
</ParamField>

<ParamField body="source_dataset_id" type="string">
  UUID or name of the source dataset. Required if `source_query` is not set.
</ParamField>

<ParamField body="target_dataset_id" type="string">
  UUID or name of the target dataset. Required if `target_query` is not set.
</ParamField>

<ParamField body="configuration" type="object" required>
  Comparison configuration.

  <Expandable title="configuration">
    <ParamField body="source_columns" type="array" required>
      List of column names to compare from the source dataset.
    </ParamField>

    <ParamField body="target_columns" type="array" required>
      List of column names to compare from the target dataset.
    </ParamField>

    <ParamField body="primary_keys_source" type="array" required>
      Primary key columns in the source dataset.
    </ParamField>

    <ParamField body="primary_keys_target" type="array" required>
      Primary key columns in the target dataset.
    </ParamField>

    <ParamField body="source_filter" type="string">
      SQL WHERE clause to filter source rows.
    </ParamField>

    <ParamField body="target_filter" type="string">
      SQL WHERE clause to filter target rows.
    </ParamField>

    <ParamField body="source_query" type="string">
      Custom SQL query for the source. Overrides `source_dataset_id`.
    </ParamField>

    <ParamField body="target_query" type="string">
      Custom SQL query for the target. Overrides `target_dataset_id`.
    </ParamField>

    <ParamField body="case_sensitive" type="boolean" default="false">
      Whether string comparisons are case-sensitive.
    </ParamField>

    <ParamField body="quick_comparison" type="boolean" default="false">
      Run a fast row-count-only comparison instead of a full diff.
    </ParamField>

    <ParamField body="schema_diff" type="boolean" default="false">
      Include schema differences in the comparison.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="data" type="object">
  The created comparison.

  <Expandable title="data">
    <ResponseField name="id" type="string">UUID of the comparison.</ResponseField>
    <ResponseField name="name" type="string">Comparison name.</ResponseField>
    <ResponseField name="source_dataset_id" type="string">Source dataset UUID.</ResponseField>
    <ResponseField name="target_dataset_id" type="string">Target dataset UUID.</ResponseField>
    <ResponseField name="configuration" type="object">The comparison configuration as stored.</ResponseField>
    <ResponseField name="workspace_id" type="string">Workspace UUID.</ResponseField>
    <ResponseField name="user_id" type="string">UUID of the user who created the comparison.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string">Status message.</ResponseField>

<RequestExample>
  ```curl cURL theme={null}
  curl -X POST "https://YOUR_BASE_URL/comparisons" \
    -H "Authorization: Bearer <api-key>" \
    -H "Workspace-Id: <workspace-id>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "orders table comparison",
      "source_datasource_id": "aaaaaaaa-0000-0000-0000-000000000001",
      "target_datasource_id": "bbbbbbbb-0000-0000-0000-000000000002",
      "source_dataset_id": "cccccccc-0000-0000-0000-000000000003",
      "target_dataset_id": "dddddddd-0000-0000-0000-000000000004",
      "configuration": {
        "source_columns": ["order_id", "customer_id", "total"],
        "target_columns": ["order_id", "customer_id", "total"],
        "primary_keys_source": ["order_id"],
        "primary_keys_target": ["order_id"]
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://YOUR_BASE_URL/comparisons"
  headers = {
      "Authorization": "Bearer <api-key>",
      "Workspace-Id": "<workspace-id>",
  }
  payload = {
      "name": "orders table comparison",
      "source_datasource_id": "aaaaaaaa-0000-0000-0000-000000000001",
      "target_datasource_id": "bbbbbbbb-0000-0000-0000-000000000002",
      "source_dataset_id": "cccccccc-0000-0000-0000-000000000003",
      "target_dataset_id": "dddddddd-0000-0000-0000-000000000004",
      "configuration": {
          "source_columns": ["order_id", "customer_id", "total"],
          "target_columns": ["order_id", "customer_id", "total"],
          "primary_keys_source": ["order_id"],
          "primary_keys_target": ["order_id"],
      },
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const payload = {
    name: "orders table comparison",
    source_datasource_id: "aaaaaaaa-0000-0000-0000-000000000001",
    target_datasource_id: "bbbbbbbb-0000-0000-0000-000000000002",
    source_dataset_id: "cccccccc-0000-0000-0000-000000000003",
    target_dataset_id: "dddddddd-0000-0000-0000-000000000004",
    configuration: {
      source_columns: ["order_id", "customer_id", "total"],
      target_columns: ["order_id", "customer_id", "total"],
      primary_keys_source: ["order_id"],
      primary_keys_target: ["order_id"],
    },
  };

  const response = await fetch("https://YOUR_BASE_URL/comparisons", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <api-key>",
      "Workspace-Id": "<workspace-id>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "message": "Comparison created successfully",
    "data": {
      "id": "eeeeeeee-0000-0000-0000-000000000005",
      "name": "orders table comparison",
      "source_dataset_id": "cccccccc-0000-0000-0000-000000000003",
      "target_dataset_id": "dddddddd-0000-0000-0000-000000000004",
      "configuration": {
        "source_columns": ["order_id", "customer_id", "total"],
        "target_columns": ["order_id", "customer_id", "total"],
        "primary_keys_source": ["order_id"],
        "primary_keys_target": ["order_id"],
        "case_sensitive": false,
        "quick_comparison": false
      },
      "workspace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_id": "ffffffff-0000-0000-0000-000000000006"
    }
  }
  ```
</ResponseExample>