> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snowflake.com/llms.txt
> Use this file to discover all available pages before exploring further.

<dl>
<dt>Categories:</dt>
<dd>

[Table functions](/sql-reference/functions-table)

</dd>
</dl>

# GET_LINEAGE (SNOWFLAKE.CORE)

This feature requires Enterprise Edition (or higher). To inquire about upgrading, please contact [Snowflake Support](https://docs.snowflake.com/user-guide/contacting-support).

- [Data Lineage](/user-guide/ui-snowsight-lineage)
- [Preserving data lineage through temporary tables and views](/user-guide/lineage-temporary-objects)

Given a Snowflake object, returns data lineage information upstream or downstream from that object. Upstream means the
path of objects that led to the creation of the object; downstream means the path of objects that were created
from the object.

## Syntax

```sqlsyntax
SNOWFLAKE.CORE.GET_LINEAGE(
    '<object_name>',
    '<object_domain>',
    '<direction>',
    [ <max_distance>, ]
    [ '<object_version>', ]
    [ '<namespace>', ]
    [ '<object_type>', ]
    [ '<external_id>', ]
    [ '<column_name>' ]
)
```

## Arguments

**Required:**

<dl>
<dt><code className="samp">'<em>object_name</em>'</code></dt>
<dd>

Name of the object for which data lineage information is retrieved. Use the fully qualified name if the object is in a
schema different from the current schema in the session.

Specify a storage integration by its unqualified name, because integrations are account-level objects.

</dd>
<dt><code className="samp">'<em>object_domain</em>'</code></dt>
<dd>

The domain of the object. Supported domains are 'COLUMN', 'TABLE' (which includes all table-like objects including
views and dynamic tables), 'SEMANTIC_VIEW' (for [semantic views](/user-guide/views-semantic/overview)), 'STAGE',
'INTEGRATION' (for [storage integrations](/sql-reference/sql/create-storage-integration)), 'STREAM', 'TASK',
'TASK_GRAPH', 'CORTEX_SEARCH_SERVICE'
(for [Cortex Search services](/user-guide/snowflake-cortex/cortex-search/cortex-search-overview)), 'MODEL MONITOR' (for
[model monitors](/developer-guide/snowflake-ml/model-registry/model-observability)), and 'CORTEX_AGENT' (for
[Cortex Agents](/user-guide/snowflake-cortex/cortex-agents)).

Specify an external table as 'TABLE'. The output reports its domain as 'EXTERNAL_TABLE'.

Specify a model monitor as 'MODEL MONITOR', with a space rather than an underscore. This is the same value that the
output reports for a model monitor.

Specify an agent as 'CORTEX_AGENT'. 'AGENT' isn't a valid domain, even though the object type is displayed as **Agent**
in %sf-web-interface%.

For ML lineage, use *TABLE* for feature views (which are dynamic tables and views internally), 'DATASET', or 'MODEL' for
models.

To retrieve lineage for an object that isn't in Snowflake, use 'EXTERNAL', or 'EXTERNAL_COLUMN' for a column of such an
object. Both require the `namespace` argument. For more information, see
[Lineage for objects outside Snowflake](#label-get-lineage-external-objects).

</dd>
<dt><code className="samp">'<em>direction</em>'</code></dt>
<dd>

The direction for which the lineage should be retained. Supported directions are 'UPSTREAM' and 'DOWNSTREAM'.

</dd>
</dl>

**Optional:**

<dl>
<dt><code className="samp"><em>max_distance</em></code></dt>
<dd>

The number of levels of lineage to retrieve. The maximum is 5; this is also the default.

</dd>
<dt><code className="samp">'<em>object_version</em>'</code></dt>
<dd>

For versioned objects, such as datasets and models, the version of the object for which lineage is retrieved. If not
specified, the default version is used.

</dd>
<dt><code className="samp">'<em>namespace</em>'</code></dt>
<dd>

The namespace of the object, which identifies the system the object comes from. Required when `object_domain` is
'EXTERNAL' or 'EXTERNAL_COLUMN', and not valid for any other domain.

</dd>
<dt><code className="samp">'<em>object_type</em>'</code></dt>
<dd>

The specific type of the object within its namespace, such as the type a data catalog assigns it. Only valid when
`object_domain` is 'EXTERNAL' or 'EXTERNAL_COLUMN'.

</dd>
<dt><code className="samp">'<em>external_id</em>'</code></dt>
<dd>

The identifier that the originating system assigns to the object. Only valid when `object_domain` is 'EXTERNAL' or
'EXTERNAL_COLUMN'.

</dd>
<dt><code className="samp">'<em>column_name</em>'</code></dt>
<dd>

The name of the column to retrieve lineage for. Required when `object_domain` is 'EXTERNAL_COLUMN', and not valid for
any other domain.

</dd>
</dl>

## Output

The output is a table with one row per object relationship in the lineage path (that is, an edge in the lineage graph).
Relationships are between objects designated as source and target in each row. The table includes the following columns:

| Column                   | Type    | Description                                                                                                                                                                                                                                                              |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SOURCE_OBJECT_DATABASE` | VARCHAR | The database that contains the source object.                                                                                                                                                                                                                            |
| `SOURCE_OBJECT_SCHEMA`   | VARCHAR | The schema that contains the source object.                                                                                                                                                                                                                              |
| `SOURCE_OBJECT_NAME`     | VARCHAR | The unqualified name of the source object.                                                                                                                                                                                                                               |
| `SOURCE_OBJECT_DOMAIN`   | VARCHAR | The domain of the source object. Possible values include 'COLUMN', 'TABLE', 'EXTERNAL_TABLE', 'SEMANTIC_VIEW', 'DATASET', 'MODEL' (for ML models), 'MODEL MONITOR', 'STAGE', 'INTEGRATION', 'STREAM', 'TASK', 'TASK_GRAPH', 'CORTEX_SEARCH_SERVICE', and 'CORTEX_AGENT'. |
| `SOURCE_OBJECT_VERSION`  | VARCHAR | The version of the source object, for versioned objects such as datasets and models. NULL if the source object is not versioned.                                                                                                                                         |
| `SOURCE_COLUMN_NAME`     | VARCHAR | The name of the source column, if the source object is a column. NULL if the source object is not a column.                                                                                                                                                              |
| `SOURCE_STATUS`          | VARCHAR | The status of the source object. Possible values are 'ACTIVE' and 'MASKED'.                                                                                                                                                                                              |
| `TARGET_OBJECT_DATABASE` | VARCHAR | The database that contains the target object.                                                                                                                                                                                                                            |
| `TARGET_OBJECT_SCHEMA`   | VARCHAR | The schema that contains the target object.                                                                                                                                                                                                                              |
| `TARGET_OBJECT_NAME`     | VARCHAR | The unqualified name of the target object.                                                                                                                                                                                                                               |
| `TARGET_OBJECT_DOMAIN`   | VARCHAR | The domain of the target object. Possible values include 'COLUMN', 'TABLE', 'EXTERNAL_TABLE', 'SEMANTIC_VIEW', 'DATASET', 'MODEL' (for ML models), 'MODEL MONITOR', 'STAGE', 'INTEGRATION', 'STREAM', 'TASK', 'TASK_GRAPH', 'CORTEX_SEARCH_SERVICE', and 'CORTEX_AGENT'. |
| `TARGET_OBJECT_VERSION`  | VARCHAR | The version of the target object, for versioned objects such as datasets and models. NULL if the target object is not versioned.                                                                                                                                         |
| `TARGET_COLUMN_NAME`     | VARCHAR | The name of the target column, if the target object is a column. NULL if the target object is not a column.                                                                                                                                                              |
| `TARGET_STATUS`          | VARCHAR | The status of the target object. Possible values are 'ACTIVE' and 'MASKED'.                                                                                                                                                                                              |
| `DISTANCE`               | INTEGER | The distance of the target object from the source object in the lineage path. A direct relationship has a distance of 1.                                                                                                                                                 |
| `PROCESS`                | VARIANT | Provides details about how lineage between the source object and target object was established. For example, it might include the query ID of a SQL query or the name of a stored procedure that moved data from the source object to the target object.                 |
| `SOURCE_DETAILS`         | VARIANT | Additional details about the source object. See [Object details](#label-get-lineage-object-details).                                                                                                                                                                     |
| `TARGET_DETAILS`         | VARIANT | Additional details about the target object. See [Object details](#label-get-lineage-object-details).                                                                                                                                                                     |

<a id="label-get-lineage-object-details"></a>

## Object details

The `SOURCE_DETAILS` and `TARGET_DETAILS` columns are populated for every object in the lineage path. Keys with no value
for a given object are omitted. Each column contains the following keys:

| Key            | Description                                                                                                                                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dataset_type` | The specific type of the object. This is more granular than `SOURCE_OBJECT_DOMAIN` and `TARGET_OBJECT_DOMAIN`; for example, an object in the `TABLE` domain can have a `dataset_type` of `TABLE` or `VIEW`. |
| `origin`       | Where the lineage for the object came from: `NATIVE` for a Snowflake object, or `OPEN_LINEAGE` for an object whose lineage was ingested from an external source.                                            |
| `namespace`    | The namespace of the object. Present for objects that aren't Snowflake objects.                                                                                                                             |
| `external_id`  | The identifier of the object in the system it originates from. Present for objects that aren't Snowflake objects.                                                                                           |

## Usage notes

- You will receive an error message if the object does not exist, if the object is not accessible to the current user,
  if the object does not support data lineage, or if the object is not in the specified domain.
- The output table contains no rows if no lineage information is available for the specified object; this is not an error.
- `GET_LINEAGE` returns at most 10 million rows, each row representing an edge (relationship) in the lineage graph.
  If there are more than 10 million rows in the output, the function silently truncates output to 10 million rows.
- You can specify arguments either by position or by name, but not both in the same call. For an
  example that uses named arguments, see [Passing arguments by name](#label-get-lineage-named-args).
- For limitations and considerations that apply to using this function, see
  [Lineage limitations and considerations](#label-lineage-limitations).

## Example

Assume you have created a table named TABLE_B from TABLE_A using CREATE TABLE AS SELECT, then created a table named
TABLE_C from TABLE_B in a similar manner. The following SQL query retrieves two steps of downstream lineage from
TABLE_A:

```sql
SELECT
    DISTANCE,
    SOURCE_OBJECT_DOMAIN,
    SOURCE_OBJECT_DATABASE,
    SOURCE_OBJECT_SCHEMA,
    SOURCE_OBJECT_NAME,
    SOURCE_STATUS,
    TARGET_OBJECT_DOMAIN,
    TARGET_OBJECT_DATABASE,
    TARGET_OBJECT_SCHEMA,
    TARGET_OBJECT_NAME,
    TARGET_STATUS,
FROM TABLE (SNOWFLAKE.CORE.GET_LINEAGE('my_database.sch.table_a', 'TABLE', 'DOWNSTREAM', 2));
```

The output is similar to the following:

```text
+----------+----------------------+------------------------+----------------------+--------------------+---------------+----------------------+------------------------+----------------------+--------------------+---------------+
| DISTANCE | SOURCE_OBJECT_DOMAIN | SOURCE_OBJECT_DATABASE | SOURCE_OBJECT_SCHEMA | SOURCE_OBJECT_NAME | SOURCE_STATUS | TARGET_OBJECT_DOMAIN | TARGET_OBJECT_DATABASE | TARGET_OBJECT_SCHEMA | TARGET_OBJECT_NAME | TARGET_STATUS |
|----------+----------------------+------------------------+----------------------+--------------------+---------------+----------------------+------------------------+----------------------+--------------------+---------------|
|        1 | TABLE                | MY_DATABASE            | SCH                  | TABLE_A            | ACTIVE        | TABLE                | MY_DATABASE            | SCH                  | TABLE_B            | ACTIVE        |
|        2 | TABLE                | MY_DATABASE            | SCH                  | TABLE_B            | ACTIVE        | TABLE                | MY_DATABASE            | SCH                  | TABLE_C            | ACTIVE        |
+----------+----------------------+------------------------+----------------------+--------------------+---------------+----------------------+------------------------+----------------------+--------------------+---------------+
```

<a id="label-get-lineage-named-args"></a>

## Passing arguments by name

You can pass arguments by name instead of by position, which lets you omit the optional arguments you
don't need. The following query returns the same lineage as the previous example:

```sql
SELECT
    DISTANCE,
    SOURCE_OBJECT_NAME,
    TARGET_OBJECT_NAME
FROM TABLE (SNOWFLAKE.CORE.GET_LINEAGE(
    object_name => 'my_database.sch.table_a',
    object_domain => 'TABLE',
    direction => 'DOWNSTREAM',
    max_distance => 2));
```

<a id="label-get-lineage-external-objects"></a>

## Lineage for objects outside Snowflake

Lineage isn't limited to objects in Snowflake. For information about capturing lineage from an external system, see
[External lineage](/user-guide/external-lineage).

After that lineage is ingested into your account, `GET_LINEAGE` reports it alongside your Snowflake lineage:

- **Objects outside Snowflake appear in the output.** A lineage path that starts at a Snowflake object can continue into
  objects that aren't in Snowflake. The `SOURCE_DETAILS` and `TARGET_DETAILS` columns identify these objects; their
  `origin` key distinguishes them from Snowflake objects. See [Object details](#label-get-lineage-object-details).

- **You can start from an object outside Snowflake.** Set `object_domain` to 'EXTERNAL' (or 'EXTERNAL_COLUMN' for one of
  its columns) and pass the object's `namespace` along with its name. This is useful for tracing which Snowflake objects
  an external object feeds, or what feeds it.

- **A chain of external objects takes one query per step.** Lineage can continue from one external object to another: for
  example, from a Snowflake table to an external object and then on to a second external object. To retrieve the next step
  in such a chain, run a second query anchored on the external object you reached.

For an object that isn't in Snowflake, `SOURCE_OBJECT_DATABASE` and `SOURCE_OBJECT_SCHEMA` (and their target equivalents)
are NULL, and the object's domain is reported as 'EXTERNAL' or 'EXTERNAL_COLUMN'.

### Example: Reaching an object outside Snowflake

Assume that TABLE_A is exported to a file, and that lineage for the export has been ingested into your account. The
following query retrieves downstream lineage from TABLE_A, extracting the namespace and origin of each target from
`TARGET_DETAILS`:

```sql
SELECT
    DISTANCE,
    SOURCE_OBJECT_NAME,
    TARGET_OBJECT_DOMAIN,
    TARGET_OBJECT_NAME,
    TARGET_DETAILS:namespace::VARCHAR AS TARGET_NAMESPACE,
    TARGET_DETAILS:origin::VARCHAR AS TARGET_ORIGIN
FROM TABLE (SNOWFLAKE.CORE.GET_LINEAGE(
    object_name => 'my_database.sch.table_a',
    object_domain => 'TABLE',
    direction => 'DOWNSTREAM',
    max_distance => 1));
```

The output is similar to the following, in which the database and schema columns are NULL for the target because the
target isn't a Snowflake object:

```text
+----------+--------------------+----------------------+--------------------+------------------------+---------------+
| DISTANCE | SOURCE_OBJECT_NAME | TARGET_OBJECT_DOMAIN | TARGET_OBJECT_NAME | TARGET_NAMESPACE       | TARGET_ORIGIN |
|----------+--------------------+----------------------+--------------------+------------------------+---------------|
|        1 | TABLE_A            | EXTERNAL             | out/daily.parquet  | s3://analytics-exports | OPEN_LINEAGE  |
+----------+--------------------+----------------------+--------------------+------------------------+---------------+
```

### Example: Continuing from an object outside Snowflake

To retrieve the lineage of the file reached in the previous example, anchor on it: set `object_domain` to 'EXTERNAL' and
pass its `namespace` along with its name. Repeat this pattern to follow a chain of external objects one step at a time.

```sql
SELECT
    DISTANCE,
    SOURCE_OBJECT_NAME,
    TARGET_OBJECT_DOMAIN,
    TARGET_OBJECT_NAME
FROM TABLE (SNOWFLAKE.CORE.GET_LINEAGE(
    object_name => 'out/daily.parquet',
    object_domain => 'EXTERNAL',
    direction => 'DOWNSTREAM',
    max_distance => 1,
    namespace => 's3://analytics-exports'));
```