SDX Technology

SDX CLI Tool

A local-first command-line tool to download and access the SDX Registry locally.

The CLI Tool also includes built-in fuzzy matching that is purpose built for mapping SDX IDs against any IDs that are stored in your local database.

• Single Binary

  Install in seconds. Runs on Linux (x86_64, arm64), macOS (arm64, x86_64), and Windows (x86_64). Zero dependencies.

• Database Support

  Supports Postgres, MySQL, and SQL Server out of the box. Connect with a standard DATABASE_URL environment variable.

• Your Data Stays Yours

  Everything runs locally in your environment. Customer data never leaves. Only an API key is sent to SDX for Auth in order to download the SDX Registry of catalogs.

Accessing the SDX Registry Catalogs

1. Download the entity catalog

   bash

   sdx catalog sync

   Downloads the SDX entity catalog as a local SQLite file. First run gets a full compressed snapshot; subsequent runs download only incremental changesets (small binary deltas). If your catalog is more than 7 days behind, the CLI automatically fetches a fresh snapshot.

Mapping SDX Registry records to existing IDs

1. Download partner ID mappings (optional)

   bash

   sdx mappings sync

   Downloads partner provider ID mapping files from the URLs configured in your sdx.yml. These mappings enable exact ID matching during resolution, the highest-confidence path. Files are cached locally with HTTP caching to avoid unnecessary downloads.

   NOTE: This command is used only if someone you are integrated with has shared a Partner Catalog with you. If you are mapping SDX IDs locally for the first time, you can skip this step.
2. Match rows & write SDX IDs

   bash

   sdx sync sdx

   The primary resolution command. It selects rows that don't yet have an SDX ID, tries to find a match (exact match, then fuzzy matching). One match writes the ID; zero matches marks the row as unresolved; multiple candidates marks it as needs_review. The command is idempotent and safe to run frequently. It only touches rows with a NULL SDX ID column.

3. Resolve IDs

   bash

   sdx sync <provider>

   Resolves IDs for non-partner providers using the SDX ID as a bridge. Calls your fetch script to get the provider's entity list as JSON, resolves each against the SDX catalog, and writes the provider ID to your rows via the SDX ID bridge.

Configuration

The CLI is configured with an sdx.yml file in your project directory. This file tells the CLI which database tables contain sports entities, how to match them, and where to write IDs. It has two sections: providers (define the data sources whose IDs appear in your database) and entities (map your database tables to SDX entity types).

# sdx.yml — example configuration
providers:
  sdx:
    name: "SDX"
    type: partner
  partner_a:
    name: "Partner A"
    type: partner
    mappings:
      entities:
        player:
          url: "https://data.partner-a.com/sdx/mappings/players.json"

entities:
  - competition: comp_xxxxx
    entity: player
    table: mlb_players
    primary_key: id
    match_fields:
      name: [first_name, last_name]
      team: [mlb_teams.location, mlb_teams.mascot]
    provider_ids:
      sdx:
        column: sdx_id
      partner_a:
        column: partner_a_id

Reviewing & Status Tracking

When the CLI encounters rows that can't be resolved (either no match found or multiple candidates returned), it logs them to a CSV file for manual review. Use sdx review to see a summary of resolution status across all your entities and providers: how many are resolved, unresolved, or need review. Filter by competition, entity type, or provider as needed.

Safety Guarantees

• Never overwrites existing IDs

  all writes are guarded with AND column IS NULL

• Fully idempotent

  safe for cron scheduling. Overlapping runs may cause wasted work, but never corruption.

• Data stays local

  fetch scripts run in your environment with your credentials. Provider API keys never touch SDX infrastructure.

CLI Quick Reference

All available commands at a glance.