Configuring an Entity

Overview

Entity configuration is where data connection truly comes to life. This step transforms raw sources into structured, reusable event knowledge graphs — setting the foundation for dimensions, metrics, and ultimately, actionable insights. Below, we guide you through accessing, understanding, and managing your entities within the Builder.

Accessing the Entities Overview

In the Builder’s main menu, click Builder. From the submenu on the left, select Entities. You’ll arrive at a comprehensive, tabular overview of every entity you’ve defined. Think of each entity as a distinct data model encapsulating a specific domain or functional slice—whether an ERP sales module, a purchasing API, or any other data segment.

Anatomy of the Entity Table

Each row in the Entities table represents one so called Entity Graph and includes the following columns:

Actions during Entity Management

1. Configuration Settings: Click Configure to dive into the entity’s setup interface. Here you can adjust source queries, joins, and field mappings to refine how raw data flows into your model. Because this is the most intricate step in data integration—where join logic, data types, and custom transformations come together—take the time to ensure every field and relationship accurately reflects your business requirements.
2. Reset: If you’ve made configuration changes that you’d like to discard, use Reset. This reverts the entity to the last imported state, wiping away any in-progress edits and restoring a known-good configuration.
3. Import: Press Import to launch the entity build process. You’ll see the Progress column cycle through each stage—schema validation, data ingestion, and post-load checks—until it lands on Import Done. A successful import updates the Status to blue and refreshes the Imported timestamp.
4. Delete: Use the Delete action to remove the entity and all of its metadata permanently. Before confirming, ensure that no downstream dimensions or reports depend on this model.
5. Export Configuration: Click Export Configuration to download a JSON or YAML file containing the entity’s complete setup—field definitions, joins, filters, and more. Store this file in version control or a secure archive for audit trails, disaster recovery, or sharing across environments.
6. Copy Configuration: When you need a variant of an existing model—perhaps to support a different region or test new join logic—select Copy Configuration. This creates a duplicate entity, preserving all settings so you can iterate without disrupting your production model.

Import Entity Configuration from File

Above the Entities table, you’ll find an Import Configuration button (an upward-pointing arrow). Use this to upload previously exported configuration files in bulk, rapidly provisioning new models or restoring archived definitions.

Best Practices for Entity Configuration

Descriptive Naming: Adopt a consistent convention (e.g., source_module_scope) that conveys both origin and content.

Modular Designs: Break large source systems into smaller, focused entities (e.g., separate Orders, Payments, and Shipments) to simplify testing and maintenance.

Version Control: Regularly export configurations and commit them to your repository, ensuring every change is tracked and reversible.

Frequent Imports: After any change—field addition, join tweak, filter adjustment—trigger an import to validate and cement your updates.

Configuring an Entity Graph

Once you’ve located the entity you wish to refine in the Entities overview, click its Configure button to launch the entity editor. This two-step workflow guides you from selecting the right tables or API calls to defining each activity’s core attributes and SQL logic—so you end up with a data model that’s accurate, performant, and tailored to your business needs.

Choosing Your Data Objects

The first screen presents you with two panes: Available Data Objects on the left and Selected Data Objects on the right.

Available Data Objects
Here you’ll see every table, view, or API endpoint that your chosen data source exposes. If you’re connected to a relational database, the list might include sales_orders, order_items, and customers. If you’re working with a REST API, you might see endpoints such as GET /invoices or GET /shipments.

Selecting Objects
Simply drag an object across to the Selected pane or click the Add button to include it in your entity graph. Should you change your mind, remove individual objects by clicking Remove, or clear the entire selection with Remove All. Conversely, Add All populates every object in one go—handy for broad, exploratory models.

Inspecting Metadata
If you need more context before committing, click the small “info” icon beside any object. A metadata panel slides up from the bottom, showing column counts, row estimates, data sizes, and other vital statistics. This quick insight helps you decide whether a table is too large for your use case or whether an API call returns the fields you need.

When your selection reflects exactly the tables or endpoints you intend to model, click Next in the lower right corner.

Building and Configuring Each Entity

Now you’re presented with a blank canvas and a sidebar listing the Selected Data Objects. Think of each object as a tile you’ll place on this canvas to sketch out your entity graph.

Drag & Drop to Put Entities to the Canvas
Pull each data object from the sidebar onto the white canvas. As soon as you place it, the Builder generates a provisional entity element with a red exclamation mark at the side indicating that it still needs configuration.

Display the Grid
To keep your layout structured, toggle on Show Grid beneath the canvas. The faint grid lines ensure that even complex graphs remain legible and logically arranged.

Opening the Context Menu
Right-click any entity to expose three options:

Delete removes the entity if you decide it’s not relevant to this entity graph.

Add Process Context lets you annotate the entity with process context —ideal for documenting nuances like business rules or standard operating procedures (We’ll cover context fields in depth in a later section).

Configure launches the detailed entity settings dialog, which we’ll explore now.

Detailed Entity Configuration Dialog

When you click Configure, a modal window surfaces, divided into clearly labeled sections. Take the time to complete each area thoughtfully—this is where raw data transforms into meaningful, analysis-ready events.

Activity Name
At the top, enter a concise, action-oriented label following best practices from business process management: verb + subject. For example, Create Order, Issue Invoice, or Ship Item. This naming convention ensures that anyone viewing reports or dashboards immediately understands the business step represented.

Timestamps

• Start Timestamp (required): Select the column that marks when the record first entered this activity—e.g., order_date or invoice_issued_at.
• Change Timestamp (optional): Choose a column such as last_update if you want to capture rework or status changes. Including both timestamps enables metrics on both lead times and rework loops.

Properties Selection
Below the timestamps, you’ll see a searchable list of all columns imported from your selected tables or API responses. Tick the checkboxes next to each property you wish to include in your model—these become available later for filters, root-cause analyses, and enriched reporting.

Advanced SQL Queries
At the bottom of the modal, an Advanced SQL section lets you fine-tune your data retrieval:

• Custom JOIN Clauses to bring in additional tables dynamically.
• WHERE Filters to pre-filter records at source (for example, WHERE status = 'active').

Validating Your Configuration
Before saving, use the built-in validation tools:

Test Query runs your configuration against the source and returns a preview of the first few rows—perfect for spotting syntax errors or unexpected nulls.

Show Query reveals the exact SQL (or API request) the Builder will execute, giving you full transparency into the underlying logic.

Load Property List refreshes the properties panel if you’ve added tables or fields via advanced SQL.

Once you’re satisfied, click Confirm. The red exclamation mark on the outside of an entity will disappear, signifying that this node is now fully configured.

Detailed Realtionship Configuration Dialog

With each entity properly configured and imported, the next critical phase ties your models together into a cohesive graph. These relationships—mirroring the foreign-key joins or logical linkages in your underlying systems—are what transform isolated tables into a unified data architecture. Here’s how to establish them with precision.

Activating Relationship Mode

Return to your entity canvas and click the Add Data Relationships button in the upper-left corner. This puts the canvas into “relationship drawing” mode: your cursor now projects a small linking icon, ready to trace connections between entities.

Drawing the Initial Link

• Select the Source Node: Move your cursor over the entity block where the relationship originates (for instance, Order Header).
• Drag Toward the Target: Click and hold the left mouse button, drag to the destination entity (e.g., Order Items), and release.
• Observe the Placeholder: A red, dotted line appears—signaling that the relationship exists in draft form but lacks its mapping details.

Configuring the Relationship

To turn that placeholder into a fully defined join, right-click the dotted line and choose Configure from the context menu. A modal dialog opens, presenting two panels:

• Source Panel (Left): Displays the source entity’s name and the list of its available properties.
• Target Panel (Right): Shows the target entity and its properties.

Mapping Fields

At the core of any relationship is the field mapping—telling the Builder which source column corresponds to which target column: In the Target panel, locate the dropdown beside each mapped field slot. Select the matching property from the source list (for example, mapping order_id on the source to order_id on the target). If your join requires multiple columns—say, both customer_id and region_id—simply add additional mappings in the same way.

Adding Non-Key Properties

Sometimes you need to join on a field that wasn’t automatically listed (perhaps a non-key column or one introduced via advanced SQL). Scroll to the Add Property section at the bottom of the modal: Find the desired field in the autocomplete search. Click the ＋ icon to promote it into your mapping list. Map it just like a primary or foreign key. To remove any mapping, click the red trash-bin icon beside it.

Defining Complex Joins

Join Conditions: For each mapped property, you can refine the join by clicking the gear icon. This lets you specify operators (=, >, <=, etc.) or add custom SQL expressions for advanced use cases.

Bridge Tables (Cross Tables): If your model requires a many-to-many resolution via an intermediate table, click the small ＋ positioned between Source and Target. A new “Cross Table” panel appears—select your bridge table, then map fields from both sides just as you would in a direct relationship.

Directional Logic: Always map left to right, following the arrowheads on the canvas. This ensures that the Builder understands the flow of data—from source to target—when it generates SQL or orchestrates data pipelines.

Validating Your Joins

Before saving, take advantage of the built-in validation tools at the modal’s footer:

• Test Query: Executes the join logic against your source, returning a sample dataset so you can verify that the relationship produces the expected records.
• Show Query: Reveals the exact SQL statement (or API request) that the Builder will use—ensuring full transparency and allowing you to spot any syntax or logic issues immediately.

Once you’ve confirmed that the join behaves correctly, click Confirm. The dotted red line on your canvas turns solid, indicating a properly configured relationship.

With all relationships in place, your entity graph now reflects the true structure of your business data—tables joined, keys aligned, and bridge tables resolved. In the following sections, you’ll learn how to leverage this graph for advanced metric definitions, automated pipelines, and self-service analytics. But for now, take a moment to admire the map you’ve created: every node, every arrow, and every join lays the groundwork for accurate, performant insights.