Lineage FAQ

General

What is Lineage?

Lineage lets you visualize how data flows between containers and fields across your datastores. You can explore, expand, and edit connections directly in the UI.

Is Lineage available on all deployments?

Lineage is an add-on feature. It must be enabled for your deployment before the Lineage tab becomes visible. If your deployment is on a trial of the add-on, a Trial badge appears on the tab and in the Add-ons panel. Contact support if you need to extend a trial or request full access.

Does Lineage work with all datastore types?

Yes. Lineage works with both JDBC and DFS datastores, and any container or field in a connected datastore can take part in the graph.

Reading lineage out of the source automatically is narrower: that works on Snowflake, BigQuery, and Databricks. Every other datastore gets its lineage from a data catalog, from the assets Qualytics writes itself, or by hand.

Where do I access Lineage?

Open any container and click the Lineage tab. If the tab is not visible, the Lineage add-on is not enabled for your deployment.

How do I get lineage without drawing it myself?

Three ways, and they work together. Connect a data catalog that publishes lineage and it is imported on each sync. Run a Sync with Collect lineage turned on and Qualytics reads the relationships the source datastore records itself. Anything Qualytics writes, a computed container or a materialize or remediation table, carries its lineage with no setup at all.

How do I turn on lineage collection?

It is an option of the Sync operation, off by default. Open the sync settings, turn on Collect lineage, and run. It applies to Snowflake, BigQuery, and Databricks, and other datastore types ignore it. Collection starts once the rest of the sync has succeeded, so a sync that fails records no lineage.

What does collection actually read?

The source's query history, to see which tables a statement read in order to write another one, and its view definitions. Where the source keeps its own record of that, Qualytics reads it directly. Where it does not, Qualytics parses the statement text the history holds. Snowflake also publishes its own per-object lineage graph, which Qualytics reads as well. The exact relations per datastore are listed in Lineage Sources.

Should I run collection once or keep it on?

Keep it on, on the scheduled Sync. A single run sees only the relationships exercised inside the window it read, so a table written monthly is invisible to a run that swept a week. Each run adds what it sees to what is already there, so the graph fills in over time.

Graph and Navigation

What does the graph show when I first open Lineage?

The initial view shows the focal container and its immediate connections, one level upstream and one level downstream. From there you can expand the graph incrementally.

How do I expand the graph to see more connections?

Containers at the edge of the current view show expand controls on their upstream and downstream sides:

• Single chevron expands one more level in that direction.
• Double chevron follows that direction to the end of the chain instead of one step, up to 20 steps out from the node. If the chain runs longer, click again from a node at the new edge.

Can I rearrange nodes in the graph?

Yes. Click and drag any node to reposition it however works best for your analysis. These positions are not persisted and reset when you leave the page or click Reorganize in the toolbar, which re-applies the default left-to-right layout.

How do I re-center the view?

Use the Fit view button in the toolbar to fit all visible nodes into view. You can also use Focus current (toolbar → More options) to center on the focal container, or Focus selection to center on a selected node.

What are the anomaly badges on nodes?

Each container node shows a status badge: an alert icon when active anomalies exist, or a check icon when none are found. A container that has never been scanned shows no badge at all. Hovering over the badge shows the exact count. Clicking the badge (only available when anomalies exist) opens the anomaly panel filtered to that container, so you can investigate quality issues without leaving the lineage graph.

What is field-lens mode?

Clicking a field row inside a container node activates field-lens mode, which highlights the full connection chain for that specific field, showing which upstream fields it derives from and which downstream fields it feeds into. Click the same field again, click anywhere on the canvas, or press Esc to exit.

How are fields listed inside a container node?

Fields inside an expanded container node are grouped into two sections: With lineage (fields that have at least one connection) listed first, and No lineage (fields with no connections yet) listed below a divider. Scroll down to load more fields, and use the search box to filter by name.

Can I zoom the graph?

Yes. Use the + / − buttons in the toolbar, pinch-to-zoom on trackpad, or click the current zoom percentage to choose a preset.

What is a node with a dashed border?

An asset that a relationship names but that is not registered in Qualytics, shown under the name the source spells it with. It is a reference rather than an asset: nothing opens from it and it has no fields to expand. Right-click it and use Copy Name to take the full name into a search or a ticket.

Register the table in Qualytics and collect again, and it becomes an ordinary node. The connection is not duplicated, because the external side is replaced by the container.

How do I know where a connection came from?

Open the connection's provenance. For lineage collected from a source datastore it names the relation each piece of evidence was read from, what kind of evidence it was, when the relationship was last seen, and the Sync that last saw it, with the logo of whichever side computed it. For every other category it says what the category alone can say: added by hand, imported from the data catalog, parsed from a computed table's SQL, or written by a materialize or scan operation. See Where a Connection Came From.

How do I find which containers have lineage at all?

Use the Has lineage filter on the container listing. It keeps the containers with at least one connection, or the ones with none, which is the fastest way to see coverage gaps without opening tabs one by one. It answers the container's own state, not how far its graph reaches.

Edges and Connections

What is the difference between container-level and field-level connections?

A container-level connection links two containers, representing that data flows between them without specifying which fields are involved. A field-level connection links two specific fields, and can carry a note describing the transformation between them, such as UPPER(email), which is set through the API.

Can I mix containers and fields on opposite sides of a connection?

No. Both sides of a connection must be at the same granularity: either container-to-container or field-to-field. A container-to-field or field-to-container connection is not supported.

If I create a field-level connection between fields in different containers, does a container-level connection get created too?

Yes. When you manually create a field-level connection and the source and target fields belong to different containers, Qualytics automatically creates a container-level connection between those containers if one does not already exist.

What is the connection source type?

Each connection has a source type badge that indicates how it was created:

• Manual: created directly by a user in the UI or via the API.
• Qualytics managed: generated automatically by Qualytics when a computed container is created or updated, or when an operation writes a table into an enrichment datastore.
• Catalog integration: imported from a connected catalog (e.g. Atlan, Alation, Collibra, Purview, DataHub), shown with that integration's logo.
• Source collection: read out of the source datastore by a Sync run with Collect lineage turned on, shown with that datastore type's logo.

Opening a connection's provenance shows what Qualytics read to arrive at it. See Where a Connection Came From.

How do I delete a connection?

Hover over the source type badge on the connection. A delete button appears when you have the required permission. Click it to remove the connection. There is no confirmation step, and deleting a connection does not affect the underlying containers or fields.

Why did a connection come back after I deleted it?

Deleting removes the connection, not the thing that produces it. A data catalog connection returns on the next sync of that data catalog, a collected one the next time the relationship is observed, and a Qualytics managed one when the computed container is saved or the table is written again. Only a manual connection stays deleted on its own, because nothing else produces it.

Does a table Qualytics writes get lineage automatically?

Yes. A materialize operation connects the table it writes back to the container it materialized, and a scan connects a remediation table back to the container it scanned, at container level and at field level, with nothing to configure. Only a table holding the rows of a single container carries this, since that is the only case where naming one source is meaningful.

Why was a connection that no longer exists not removed by the next collection?

Because absence is not evidence. History can show that a relationship happened and can never show that one stopped: a table simply not written during the window leaves no trace. Reconciling on that silence would drop a connection every time a pipeline paused, so collected connections are only ever added or refreshed. Delete the ones that are genuinely gone.

Permissions

Who can view Lineage?

Any user with the Member role or above, once the Lineage add-on is enabled for the deployment.

Who can create or delete connections?

Only users with the Manager role can create or delete lineage connections.

Who can enable or disable the Lineage add-on?

Only Admin users can toggle the Lineage add-on on or off from the Add-ons panel. If the add-on is not available for your deployment at all, the toggle is locked. Contact support to request access.

API

Can I manage lineage connections via the API?

Yes. You can create, update, delete connections and query the lineage graph via the API. See the Lineage API page for endpoints and examples.

Does the API return assets that are not registered in Qualytics?

Yes, in their own arrays. The graph response keeps nodes and edges to managed containers only, so a client reading just those two is unaffected, and reports unmanaged assets in external_nodes and external_edges beside them. An external node's id is the string ext:<source_type>:<fqn>, and an external edge points at it through source_node_id or target_node_id instead of a container id.

Can I see what a connection was derived from through the API?

Yes. Every edge response carries an evidence array, populated for lineage collected from a source datastore and empty for the other categories. Each entry names the provider, the kind of evidence, which side computed it, the relation it was read from, and the Sync operations that first and last observed it.