v4 macOS container Quickstart

Run Senzing v4 on Apple Silicon Macs using Apple’s container CLI instead of Docker Desktop.

Depending on the speed of your internet connection, this may only take you a few minutes.

Prerequisites

• macOS 26 or later on Apple Silicon (M1/M2/M3/M4).
• Apple’s container CLI installed via Homebrew :

brew install container

• The container system service started:

container system start

• A PostgreSQL database set up and tuned , and the username, password, IP address, port, and database name needed to connect.
• For air-gapped deployments, see the v4 Air-Gapped Quickstart .

Container images

Getting it done

Pull the images

container image pull senzing/init-database:latest
container image pull senzing/senzingsdk-tools
container image pull senzing/sz-file-loader

Setting up - SENZING_ENGINE_CONFIGURATION_JSON

The Senzing engine configuration is set via the SENZING_ENGINE_CONFIGURATION_JSON environment variable. This is further described here .

To set the environment variable, run the following in your environment, replacing the CONNECTION details with those of your database:

export SENZING_ENGINE_CONFIGURATION_JSON='{"PIPELINE":{"CONFIGPATH":"/etc/opt/senzing","RESOURCEPATH":"/opt/senzing/er/resources","SUPPORTPATH":"/opt/senzing/data"},"SQL":{"CONNECTION":"postgresql://username:password@hostname:5432:database"}}'

Formatted for readability:

export SENZING_ENGINE_CONFIGURATION_JSON='{ \
  "PIPELINE": { \
    "CONFIGPATH": "/etc/opt/senzing", \
    "RESOURCEPATH": "/opt/senzing/er/resources", \
    "SUPPORTPATH": "/opt/senzing/data" \
  }, \
  "SQL": { \
    "CONNECTION": "postgresql://username:password@hostname:5432:database" \
  } \
}'

Initialize the Senzing repository database

It takes only a few seconds to initialize the Senzing repository database. Once SENZING_ENGINE_CONFIGURATION_JSON is set, the setup is a single command that uses the senzing/init-database image.

Initialization first adds the Senzing schema and then the Senzing Entity Resolution Configuration to the database.

container run --rm -e SENZING_ENGINE_CONFIGURATION_JSON senzing/init-database --install-senzing-er-configuration

DONE - Yes, REALLY

At this point, the Senzing database is initialized. You can run any of the Senzing v4 container images by following this pattern. Yes, REALLY.

Run the senzingsdk-tools container

Use the senzing/senzingsdk-tools image to run the senzingsdk-tools container:

container run --rm -it -e SENZING_ENGINE_CONFIGURATION_JSON senzing/senzingsdk-tools

Load the truth set data

To get started with some data, load the Senzing example truth set by:

Understanding the truth set files

The truth set demo includes three main types of files, each serving a distinct purpose in entity resolution:

• Customers: Represent your subjects of interest such as these customers. But they could easily be employees for insider threat detection, vendors for supply chain management, or other tracked entities. These records form the core dataset you aim to analyze and resolve.
• Watchlist: Contains entities you want to avoid due to potential risks. Examples include past fraudsters, known terrorists, money launderers, or entities on mandated exclusion lists (e.g., sanctions lists like OFAC). By integrating watchlist data, Senzing helps you identify high-risk entities by matching them against your subject records. This enables risk assessment by flagging connections to undesirable entities, helping you mitigate threats like fraud, regulatory non-compliance, or reputational damage.
• Reference List: Includes supplemental data purchased or acquired about individuals (e.g., demographics, past addresses, contact methods) or companies (e.g., firmographics, corporate structure, executives, ownership). This data enriches your understanding of your subjects by providing additional context, such as historical addresses to track entity movement or corporate hierarchies to identify ultimate beneficial owners. This deeper insight improves entity resolution accuracy and supports use cases like customer profiling or due diligence.

Download the files

Download the truth set files to your current directory:

wget https://raw.githubusercontent.com/Senzing/truth-sets/main/truthsets/demo/customers.jsonl

wget https://raw.githubusercontent.com/Senzing/truth-sets/main/truthsets/demo/reference.jsonl

wget https://raw.githubusercontent.com/Senzing/truth-sets/main/truthsets/demo/watchlist.jsonl

Add the data sources

container run --rm -it -e SENZING_ENGINE_CONFIGURATION_JSON senzing/senzingsdk-tools

sz_configtool

Type help or ? for help

addDataSource CUSTOMERS

Data source successfully added!

addDataSource REFERENCE

Data source successfully added!

addDataSource WATCHLIST

Data source successfully added!

save

WARNING: This will immediately update the current configuration in the Senzing repository with the current configuration!

Are you certain you wish to proceed and save changes? (y/n)

y

Configuration changes saved

quit

Load the files

Keep in mind that the file path is from the perspective of the container and this example requires the location of the files (${PWD} in this case) to be mapped into /data inside the container.

container run -it --rm -u $UID -v ${PWD}:/data -e SENZING_ENGINE_CONFIGURATION_JSON senzing/sz-file-loader -f /data/customers.jsonl

container run -it --rm -u $UID -v ${PWD}:/data -e SENZING_ENGINE_CONFIGURATION_JSON senzing/sz-file-loader -f /data/reference.jsonl

container run -it --rm -u $UID -v ${PWD}:/data -e SENZING_ENGINE_CONFIGURATION_JSON senzing/sz-file-loader -f /data/watchlist.jsonl

Explore the results

container run --rm -it -e SENZING_ENGINE_CONFIGURATION_JSON senzing/senzingsdk-tools

See EDA Tools: sz_explorer

sz_explorer

  ____|  __ \     \
  __|    |   |   _ \   Senzing
  |      |   |  ___ \  Exploratory Data Analysis
 _____| ____/ _/    _\


Type help or ? to list commands.

(szeda) get CUSTOMERS 1070

Entity summary for entity 98: Jie Wang
┼───────────┼────────────────────────────────────────┼─────────────────┼
│ Sources   │ Features                               │ Additional Data │
┼───────────┼────────────────────────────────────────┼─────────────────┼
│ CUSTOMERS │ NAME: Jie Wang (PRIMARY)               │ AMOUNT: 100     │
│ 1069      │ NAME: 王杰 (NATIVE)                    │ AMOUNT: 200     │
│ 1070      │ DOB: 9/14/93                           │ DATE: 1/26/18   │
│           │ GENDER: Male                           │ DATE: 1/27/18   │
│           │ GENDER: M                              │ STATUS: Active  │
│           │ ADDRESS: 12 Constitution Street (HOME) │                 │
│           │ NATIONAL_ID: 832721 Hong Kong          │                 │
│           │ NATIONAL_ID: 832721                    │                 │
│           │ RECORD_TYPE: PERSON                    │                 │
┼───────────┼────────────────────────────────────────┼─────────────────┼
│ REFERENCE │ NAME: Wang Jie (PRIMARY)               │ CATEGORY: Owner │
│ 2013      │ DOB: 1993-09-14                        │ STATUS: Current │
│           │ RECORD_TYPE: PERSON                    │                 │
│           │ REL_POINTER: 2011 (OWNS 60%)           │                 │
┼───────────┼────────────────────────────────────────┼─────────────────┼
└── Disclosed relation (1)
    └── --> OWNS 60% (1)
        └── 182: Hajah Mamunah Jln Pisang CUSTOMERS (1) | REFERENCE (1) +REL_POINTER(OWNS 60%:)

Mapping your own data

At this point you are ready to map and load your own data. Mapping is the process of converting your source data into a structure Senzing understands ready to load.

Consider these examples, in your data an attribute describing a personal full name is in a database table with the column name fullname. In Senzing a full name is represented by the term NAME_FULL. Similarly for address line 1, your database column is named addressline1, in Senzing this is represented by the term ADDR_LINE1.

Your task in mapping is to determine which attributes in your data source(s) are appropriate for use in entity resolution, extract those attributes and construct the structure describing those attributes to send to Senzing. The following is an example of a Senzing mapped JSON structure for an entry from a data source.

{
  "DATA_SOURCE": "CUSTOMERS",
  "RECORD_ID": "1001",
  "RECORD_TYPE": "PERSON",
  "PRIMARY_NAME_LAST": "Smith",
  "PRIMARY_NAME_FIRST": "Robert",
  "DATE_OF_BIRTH": "12/11/1978",
  "ADDR_TYPE": "MAILING",
  "ADDR_LINE1": "123 Main Street, Las Vegas NV 89132",
  "PHONE_TYPE": "HOME",
  "PHONE_NUMBER": "702-919-1300",
  "EMAIL_ADDRESS": "[email protected]"
}

Start developing

Members of our team have created GitHub projects that show more of what you can do quickly:

• Senzing in 3 Python Calls
• Python: Task-based code snippets , Streamlined RabbitMQ consumer , SQS consumer , scalable search , and redo record processing examples