Span

span_data is a Python library for customer data resolution and unification.

Early release. This package is under active development, and the public API and import paths may change between releases. We expect to follow semantic versioning more strictly after a 1.0 stable baseline; until then, treat upgrades as potentially breaking. Pin a specific version in production and review span_data/packaging_info/CHANGELOG.md before upgrading.

Modules

id_grapher

Identity resolution built on Splink and DuckDB. Links records that refer to the same entity across one or more source datasets and produces a unified ID graph keyed on profile_id.

from span_data.id_grapher import IDGrapher, FieldDefinitionMap, Overrides

Key capabilities:

• Ingest source data from pandas DataFrames, CSV files, and Snowflake tables or views.
• Clean and normalise source fields (text, email, phone number).
• Resolve entities into profile clusters with Splink-based probabilistic matching.
• Export graph results to DataFrames, CSV, Parquet, DuckDB relations, and Snowflake.
• Apply manual override workflows for merge, split, and assign operations.

See Span Product Documentation and the in-package guide span_data/packaging_info/USAGE.md (ships with the wheel) for usage examples.

c360_compiler

Customer 360 pipeline built on DuckDB. Driven by a SpanConfig (span_data.io.SpanConfig) via C360Compiler.from_span_config.

from span_data.c360_compiler import C360Compiler
from span_data.io import load_span_config

span_config = load_span_config("span_config.yaml")
compiler = C360Compiler.from_span_config(span_config, app_name="MY_DB")

SpanConfig

Unified configuration for ID Graph and C360. Load from YAML, validate, and run locally with the span-data CLI:

span-data validate-config span_config.yaml
span-data run span_config.yaml --data-dir ./data --output-dir ./out

Input CSVs under --data-dir are named {derive_source_name(dataset)}.csv (for example ANALYTICS.SOURCES.CRM_CONTACTS → ANALYTICS_SOURCES_CRM_CONTACTS.csv).

from span_data.io import load_span_config
from span_data.io.config.adapters import to_splink_config, to_c360_compiler_config

Key capabilities:

• Merge customer demographics from multiple dimension sources with configurable waterfall precedence.
• Compute rolling-window metrics (6-month, 12-month, lifetime) from fact tables.
• Build a consent fact table with two-tier taxonomy (purpose / medium) and conflict resolution.
• Generate boolean and categorical customer segments.
• Enrich fact tables with profile_id and deterministic hash keys.

See Span Product Documentation and the in-package guide span_data/packaging_info/USAGE.md (ships with the wheel) for configuration reference and usage.

Python Support

This package supports Python >=3.11 (3.11–3.14), shipped as a cp311-abi3 wheel.

Usage

See Span Product Documentation for usage instructions.

License

This project is licensed under the BSD 3-Clause License. See span_data/packaging_info/LICENSE.

Third-party dependency license information is documented in span_data/packaging_info/THIRD_PARTY_NOTICES.md.

Release history is documented in span_data/packaging_info/CHANGELOG.md.