Local Quickstart

Get started with Kanoniv in under 5 minutes. This guide walks through writing an identity schema, validating locally, and reconciling data.

New: Zero-YAML Pipeline

Don't want to write YAML? The Cloud CLI auto-discovers your data and generates a complete schema automatically. See the Cloud Quickstart or the Full Pipeline Tutorial.

Prerequisites

Python 3.9+

1. Install the SDK

bash

pip install kanoniv

2. Write an Identity Schema

Create customer-schema.yaml - this single file defines your entire identity resolution logic:

yaml

api_version: kanoniv/v1
identity_version: "1.0"

entity:
  name: customer

sources:
  crm:
    adapter: csv
    location: crm.csv
    primary_key: id
    schema:
      name: { type: string }
      email: { type: string, pii: true }
      phone: { type: string, pii: true }
      company: { type: string }

  billing:
    adapter: csv
    location: billing.csv
    primary_key: customer_id
    schema:
      full_name: { type: string }
      email: { type: string, pii: true }
      plan: { type: string }

rules:
  - name: email_exact
    type: exact
    field: email
    weight: 1.0

  - name: name_fuzzy
    type: similarity
    field: name
    algorithm: jaro_winkler
    threshold: 0.88
    weight: 0.6

survivorship:
  strategy: source_priority
  source_order: [crm, billing]

decision:
  scoring: weighted_sum
  thresholds:
    match: 0.85
    review: 0.6

The adapter field declares what kind of source this is. Here we use csv for local files. For production warehouses (Snowflake, PostgreSQL, BigQuery, etc.), change the adapter to match your source type and load data using Source.from_warehouse() in Python - see Source Adapters.

3. Validate and Reconcile Locally

No server needed. Validate the schema and run reconciliation entirely offline:

python

from kanoniv import Spec, Source, validate, reconcile

# Load and validate
spec = Spec.from_file("customer-schema.yaml")
result = validate(spec)
if not result:
    for e in result.errors:
        print(f"  {e}")
    raise SystemExit(1)
print("Schema is valid!")

# Load data and reconcile
sources = [
    Source.from_csv("crm", "crm.csv"),
    Source.from_csv("billing", "billing.csv"),
]
result = reconcile(sources, spec)

print(f"Golden records: {len(result.golden_records)}")
print(f"Merge rate: {result.merge_rate:.1%}")

# Export to pandas
df = result.to_pandas()
print(df.head())

For a complete walkthrough with sample data, see First Reconciliation.

Next Steps

First Reconciliation: Full walkthrough with sample data
Core Concepts: Understand entities, matching, survivorship
Identity Schema Configuration: Every schema configuration option
Source Adapters: Connect to warehouses, dbt, and more
Tutorials: Step-by-step guided builds

Ready for production?

Kanoniv Cloud adds a persistent identity graph, sub-millisecond resolution API, audit logs, PII masking, and governance. Same schema, same SDK - just add pip install kanoniv[cloud].

Local Quickstart ​

Prerequisites ​

1. Install the SDK ​

2. Write an Identity Schema ​