You are viewing documentation for an older version.
Click here to view the latest documentation.

ID Stitcher

Learn about the ID stitcher model in Profiles.

2 minute read

The ID stitcher model maps and unifies all the specified identifiers across inputs. It tracks the user journey uniquely across all the data sources and stitches them together to a rudder_id.

When you define an ID stitcher model in profiles.yaml, you must also reference it from the corresponding entity in pb_project.yaml.
Set id_stitcher: models/<model_name> on the entity (for example, id_stitcher: models/user_id_stitcher for the user entity). If this is missing, the intended ID stitcher is not used and you may get unintended results.

Video walkthrough

Overview

You can define an ID stitcher in the pb_project.yaml file:

models:
    - name: model_name
      model_type: `id_stitcher`
      model_spec:
          entity_key: entity_name
          materialization:
              run_type: discrete/incremental
          incremental_timedelta: 96h
          edge_sources:
              - from: path/to_inputs_table
              - from: path/to_inputs_table

Field	Description
`name`	Model name.
`model_type`	Model type - set this parameter to `id_stitcher` to implement an ID stitcher.
`model_spec`	Defines the model configuration.
`entity_key`	Specifies the entity to stitch.
`run_type`	Run type - set this parameter to `discrete` or `incremental`. (Default is incremental).
`incremental_timedelta`	In incremental ID stitching, only events from the last run are typically processed to update the ID graph. However, since events can arrive in the warehouse with delays, this parameter adds a buffer period to ensure completeness. The ID stitcher will process events starting from `incremental_timedelta` before the last run timestamp, creating an overlap window to capture any delayed events. Default value: 4 days (96 hours).
`edge_sources`	List of inputs from `inputs.yaml` and `sql-models.yaml` used for identity stitching.

Example

models:
    - name: user_id_stitcher
      model_type: id_stitcher
      model_spec:
          entity_key: user
          materialization:
              run_type: incremental
          incremental_timedelta: 96h
          edge_sources:
              - from: inputs/rsIdentifies
              - from: inputs/rsTracks

Metadata logging

Two optional model spec flags control metadata logging for nodes and direct edges in the resulting Identity Graph. Both flags are supported for Snowflake and BigQuery.

Flag	Default value	Description
`log_direct_edge_info`	`false`	Populates `direct_edge_info.edges_by_type` on the per-row `METADATA` column with connected node IDs, their `first_seen_at` timestamps, and a per-source provenance array.
`log_node_metadata`	`false`	Populates `node_info` on the per-row `METADATA` column with one entry per input model that contributed the node.

models:
    - name: user_id_stitcher
      model_type: id_stitcher
      model_spec:
          entity_key: user
          log_direct_edge_info: true
          log_node_metadata: true
          edge_sources:
              - from: inputs/rsIdentifies
              - from: inputs/rsTracks

For the metadata column structure, per-source contract, and incremental-run behavior, see Metadata and observability.

When cardinality rules are enabled on the entity, the metadata column also carries cardinality_info on capped edges, and the <material>_<entity>_CARDINALITY_AUDIT table records every dropped edge along with the input model that contributed it.

ID Stitcher

Video walkthrough

Overview

Example

Metadata logging

Questions? We're here to help.