Quickstart

This guide walks through the whole path: create a workspace, connect two data sources, define a reconciliation job, trigger a run, and fetch the results. Pick one tab and follow it straight through — each step builds on the IDs from the one before it.

All examples assume DATARECS_API_KEY is set (for the CLI and REST tabs) and that you’re targeting https://api.datarecs.io (the default).

1. Create a workspace

Console

1. Log in to the DataRecs Console.
2. Click New Workspace from the workspace selector.
3. Enter a name and click Create.

CLI

datarecs auth login --company your-company-slug
datarecs workspaces create --name "quickstart" --description "Quickstart workspace"

auth login is a device-code flow and needs your company (tenant) slug via --company.

Terraform

resource "datarecs_workspace" "quickstart" {
  name        = "quickstart"
  description = "Quickstart workspace"
}

REST API

curl -X POST https://api.datarecs.io/workspaces \
  -H "Authorization: Bearer $DATARECS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "quickstart", "description": "Quickstart workspace", "metadata": {}}'

Note the returned id — every following step needs it as workspace_id.

2. Add two connections

A reconciliation job compares exactly two sources, so create one connection per source. This example uses Postgres for both; credentials is a flat object whose shape differs by connector type — see Creating a connection for every type.

Console

1. Navigate to Connections in the sidebar.
2. Click New Connection.
3. Select your database type, enter credentials, and click Test & Save.
4. Repeat for the second source.

CLI

connections create needs a JSON file for database credentials — there’s no --host/--port flag path for SQL sources:

source-a.json

{
  "name": "source-a",
  "type": "postgres",
  "workspace_id": "<workspace-id>",
  "credentials": {
    "host": "db-a.example.com",
    "port": 5432,
    "database": "sales",
    "username": "readonly_user",
    "password": "..."
  }
}

datarecs connections test --file source-a.json
datarecs connections create --file source-a.json
# repeat with source-b.json for the second connection

Terraform

resource "datarecs_connection" "source_a" {
  name         = "source-a"
  type         = "postgres"
  workspace_id = datarecs_workspace.quickstart.id
  credentials = {
    host     = "db-a.example.com"
    port     = "5432"
    database = "sales"
    username = "readonly_user"
    password = var.source_a_password
  }
}
# repeat a "source_b" resource for the second connection

REST API

curl -X POST https://api.datarecs.io/connections \
  -H "Authorization: Bearer $DATARECS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "source-a",
    "type": "postgres",
    "workspace_id": "<workspace-id>",
    "credentials": {
      "host": "db-a.example.com",
      "port": 5432,
      "database": "sales",
      "username": "readonly_user",
      "password": "..."
    }
  }'
# repeat for source-b

Note both ids — you’ll reference them as connection_id in the job below.

3. Define a job

A job needs, at minimum, one dimension, one measure, the two connections (with column mappings), and one stage. This example counts rows per region:

Console

1. Navigate to Jobs and click New Job.
2. Pick your two connections, map their columns to shared dimension/measure names, and add a stage.
3. Save.

CLI

job.json

{
  "name": "quickstart-job",
  "workspace_id": "<workspace-id>",
  "dimensions": ["Region"],
  "measures": [
    { "name": "rowcount", "aggregation": "COUNT_STAR" }
  ],
  "connections": [
    {
      "connection_id": "<source-a-id>",
      "source_schema": "public",
      "source_table": "orders",
      "column_mapping": { "Region": "region" }
    },
    {
      "connection_id": "<source-b-id>",
      "source_schema": "public",
      "source_table": "orders",
      "column_mapping": { "Region": "region" }
    }
  ],
  "stages": [
    {
      "dimensions": ["Region"],
      "tolerances": [
        { "measure_name": "rowcount", "type": "ABSOLUTE", "value": 0 }
      ]
    }
  ],
  "stage_execution_strategy": "DRILL_DOWN_ON_FAILURE"
}

datarecs jobs create --file job.json

Terraform

resource "datarecs_job" "quickstart" {
  name         = "quickstart-job"
  workspace_id = datarecs_workspace.quickstart.id
  dimensions   = ["Region"]

  measures = [
    { name = "rowcount", aggregation = "COUNT_STAR" }
  ]

  connections = [
    {
      connection_id  = datarecs_connection.source_a.id
      source_schema  = "public"
      source_table   = "orders"
      column_mapping = { Region = "region" }
    },
    {
      connection_id  = datarecs_connection.source_b.id
      source_schema  = "public"
      source_table   = "orders"
      column_mapping = { Region = "region" }
    }
  ]

  stages = [
    {
      dimensions = ["Region"]
      tolerances = [
        { measure_name = "rowcount", type = "ABSOLUTE", value = 0 }
      ]
    }
  ]
}

REST API

curl -X POST https://api.datarecs.io/jobs \
  -H "Authorization: Bearer $DATARECS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quickstart-job",
    "workspace_id": "<workspace-id>",
    "dimensions": ["Region"],
    "measures": [{ "name": "rowcount", "aggregation": "COUNT_STAR" }],
    "connections": [
      { "connection_id": "<source-a-id>", "source_schema": "public", "source_table": "orders", "column_mapping": { "Region": "region" } },
      { "connection_id": "<source-b-id>", "source_schema": "public", "source_table": "orders", "column_mapping": { "Region": "region" } }
    ],
    "stages": [
      { "dimensions": ["Region"], "tolerances": [{ "measure_name": "rowcount", "type": "ABSOLUTE", "value": 0 }] }
    ],
    "stage_execution_strategy": "DRILL_DOWN_ON_FAILURE"
  }'

Every field here is explained in full in Configuring a Reconciliation Job.

4. Trigger a run

Terraform manages job definitions, not one-off runs — trigger from the Console, CLI, or REST API:

Console

Open the job and click Run now.

CLI

datarecs jobs runs trigger <job-id> --workspace-id <workspace-id>

Terraform

Not applicable — trigger from the Console, CLI, or REST API instead. Use datarecs_job_schedule if you want DataRecs to trigger runs on a cron schedule.

REST API

curl -X POST https://api.datarecs.io/jobs/<job-id>/runs/trigger \
  -H "Authorization: Bearer $DATARECS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "<job-id>"}'

Note the returned run_id.

5. Fetch the results

Console

Open the run from the job’s run history to see the summary and any mismatched rows.

CLI

datarecs jobs runs results view <job-id> <run-id> --workspace-id <workspace-id>

Terraform

Not applicable — results are read via the Console, CLI, or REST API.

REST API

curl https://api.datarecs.io/jobs/<job-id>/runs/<run-id>/results/summary \
  -H "Authorization: Bearer $DATARECS_API_KEY"

Next steps

• Connections in depth
• Configuring a Reconciliation Job
• Running a Reconciliation