Understand keys and relationships
Before joining datasets or building an aggregate, determine what each row means and which columns identify it. A key finding describes identifiers and uniqueness within a table; a relationship finding describes how columns in two tables appear to connect.
For example, an orders table with one row per line may repeat order_id legitimately. Summing order-level totals across those lines can overcount even though a customer join is valid. Understanding the table's grain is part of designing the calculation.
Analysis follows publication
After file-backed ingestion or transform output is published, schema discovery supplies column metadata. Separate knowledge graph work then evaluates keys and relationships:
- Key analysis investigates candidate identifiers, uniqueness, and row grain.
- Relationship analysis compares eligible tables whose key analysis covers their current published data.
- Findings and evaluation outcomes are saved for the analyzed snapshots.
A successful sync or transform can therefore have readable rows while key or relationship work is still running. Use the rows and schema for a known-column query; wait for relevant analysis before relying on inferred joins.
Read the outcome, not just completion
A relationship evaluation can report relationships_found, no_relationship_found, or inconclusive. Completion means the evaluation finished, not that a valid join was discovered.
Inspect source/target columns, cardinality, matching logic, and the reason given. Check that these match your intended business meaning and the actual rows. Inferred keys do not automatically create PostgreSQL primary-key constraints, and relationship metadata does not enforce referential integrity on analytical tables.
Later publications can reuse findings when their schema and uniqueness checks show no meaningful change. Findings remain tied to the relevant publication; compare their status with the data you are actually using.
Inspect findings in the platform
Open a table and choose Relationships. The view shows key findings, relationship evaluations, discovery phase/status, and a link to inspect the discovery job. A relationship can link to the exact compared snapshot of the other table.
Use that snapshot when validating the finding. A newer publication of the other table may have different rows or schema, even though its table ID is unchanged. For file-backed tables, select the intended preview/deployed publication before reading the findings.
Platform screenshot placeholder: A table's Relationships view with key findings, a completed relationship, its column mapping/cardinality, and “View compared snapshot.”
Observe progress from the CLI
vortexify tables --json
vortexify table TABLE_ID --json
vortexify job DISCOVERY_JOB_ID --waitThe inventory and table details expose knowledge graph progress and its job ID when available. The current CLI table request does not ask for the detailed include_analysis payload; use the platform Relationships view for those key and pair findings. There is no separate CLI command to create or edit a relationship.
Inspect both tables when planning a join. One table's analysis may finish before the second table becomes eligible for comparison. An absent evaluation is different from a completed evaluation finding no relationship.
Team-declared relationships
The API also stores team-declared column relationships separately from discovered findings. A declared relationship records source/target tables and columns, cardinality, and a description. Its columns are checked against current schemas; the declaration itself does not run a uniqueness or matching-data analysis.
Use the relationship services for those explicit declarations. The current mounted table view displays publication discovery findings, so do not treat a proposed relationship editor as an existing control. Database primary/foreign-key enforcement belongs in SQL migrations.
Continue with SQL queries to validate a join or tables and publications to inspect the data behind a finding.