MCP Tools Reference: datalineage.googleapis.com

Tool: search_lineage

Performs a breadth-first search (upstream or downstream) to retrieve lineage links for an asset identified by its Fully Qualified Name (FQN). Supports Column-Level Lineage (CLL), including wildcards to retrieve all CLL for an entity FQN.
The search_lineage method also retrieves link-creating processes if max_process_per_link is not zero and links.processes.process is requested in the FieldMask.
Required project permissions for stored links and processes are as follows:
- datalineage.events.get for links stored for entity-level lineage
- datalineage.events.getFields for links stored for column-level lineage
- datalineage.processes.get for processes.

The following sample demonstrate how to use curl to invoke the search_lineage MCP tool.

Curl Request 
                  
curl --location 'https://datalineage.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_lineage",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

Request message for SearchLineageStreaming.

SearchLineageStreamingRequest

JSON representation 
{
  "parent": string,
  "locations": [
    string
  ],
  "rootCriteria": {
    object (RootCriteria)
  },
  "direction": enum (SearchDirection),
  "filters": {
    object (SearchFilters)
  },
  "limits": {
    object (SearchLimits)
  }
}
Fields
parent

string

Required. The project and location to initiate the search from.
locations[]

string

Required. The locations to search in. This list should contain the location from the parent field.
rootCriteria

object (RootCriteria)

Required. Criteria for the root of the search.
direction

enum (SearchDirection)

Required. Direction of the search.
filters

object (SearchFilters)

Optional. Filters for the search.
limits

object (SearchLimits)

Optional. Limits for the search.

RootCriteria

JSON representation 
{

  // Union field criteria can be only one of the following:
  "entities": {
    object (MultipleEntityReference)
  }
  // End of list of possible types for union field criteria.
}
Fields
Union field criteria. Criteria for the root of the search. criteria can be only one of the following:
entities

object (MultipleEntityReference)

Optional. The entities to initiate the search from. Entities can be specified by FQN only, or by FQN and field. To search by FQN and all available fields for that FQN, use the wildcard * as the field value.

MultipleEntityReference

JSON representation 
{
  "entities": [
    {
      object (EntityReference)
    }
  ]
}
Fields
entities[]

object (EntityReference)

Optional. The list of entities to search for links. The maximum number of entities is 20.

EntityReference

JSON representation 
{
  "fullyQualifiedName": string,
  "field": [
    string
  ]
}
Fields
fullyQualifiedName

string

Required. Fully Qualified Name (FQN) of the entity.
field[]

string

Optional. Field path within the entity. Each nesting level should be a separate value in the repeated field. The order matters. Must be empty for asset level lineage

For example to address "salary.net" subfield where "salary" is a column and "net" is a proto field two values in the field should be reported, the first is "salary" and the second is "net".

Each field length is limited to 500 characters. Maximum supported nesting level is 20.

SearchFilters

JSON representation 
{
  "dependencyTypes": [
    enum (DependencyType)
  ],
  "entitySet": enum (EntitySet),
  "timeRange": {
    object (Interval)
  }
}
Fields
dependencyTypes[]

enum (DependencyType)

Optional. Types of dependencies between entities to retrieve. If unspecified, all dependency types are returned.
entitySet

enum (EntitySet)

Optional. Entity set restriction. If unspecified, the method returns all entities.
timeRange

object (Interval)

Optional. Time interval to search for lineage. If unspecified, all lineage is returned. Currently, at most one of start_time and end_time can be set.

Interval

JSON representation 
{
  "startTime": string,
  "endTime": string
}
Fields
startTime

string (Timestamp format)

Optional. Inclusive start of the interval.

If specified, a Timestamp matching this interval will have to be the same or after the start.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Optional. Exclusive end of the interval.

If specified, a Timestamp matching this interval will have to be before the end.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

Timestamp

JSON representation 
{
  "seconds": string,
  "nanos": integer
}
Fields
seconds

string (int64 format)

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z).
nanos

integer

Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive.

SearchLimits

JSON representation 
{
  "maxDepth": integer,
  "maxResults": integer,
  "maxProcessPerLink": integer
}
Fields
maxDepth

integer

Optional. The maximum depth of the search. The default value is 5 and maximum value is 100.
maxResults

integer

Optional. The maximum number of links to return in the response. The default value is 1_000 and the maximum value is 10_000.
maxProcessPerLink

integer

Optional. The maximum number of processes to return per link. The default value is 0 and the maximum value is 100. If this value is non-zero, the response will contain process names for the links. To retrieve full process details in the response, include links.processes.process in the FieldMask.

SearchDirection

Direction of the search.

Enums
SEARCH_DIRECTION_UNSPECIFIED Direction is unspecified.
DOWNSTREAM Retrieve links that lead from the specified asset to downstream assets.
UPSTREAM Retrieve links that lead from upstream assets to the specified asset.

DependencyType

Type of dependency between entities.

Enums
DEPENDENCY_TYPE_UNSPECIFIED Dependency type unspecified.
EXACT_COPY Exact data copy without any change.
OTHER Other types of dependencies like filtering or grouping.

EntitySet

Entity set restriction.

Enums
ENTITY_SET_UNSPECIFIED The entity set is unspecified. Returns all the data.
ENTITIES Returns entities with only FQN specified. For example, entities with the field field set are not returned.

Output Schema

Response message for SearchLineageStreaming.

SearchLineageStreamingResponse

JSON representation 
{
  "links": [
    {
      object (LineageLink)
    }
  ],
  "unreachable": [
    string
  ]
}
Fields
links[]

object (LineageLink)

Output only. The lineage links that match the search criteria. Can be empty if no links match.
unreachable[]

string

Unordered list. Unreachable resources. If non-empty, the result set might be incomplete.

Currently, only locations are supported.

Format: projects/[PROJECT_NUMBER]/locations/[LOCATION] Example: projects/123456789/locations/us-east1
JSON representation 
{
  "source": {
    object (EntityReference)
  },
  "target": {
    object (EntityReference)
  },
  "processes": [
    {
      object (LineageProcess)
    }
  ],
  "dependencyInfo": [
    {
      object (DependencyInfo)
    }
  ],
  "depth": integer,
  "location": string
}
Fields
source

object (EntityReference)

The entity that is the source of this link.
target

object (EntityReference)

The entity that is the target of this link.
processes[]

object (LineageProcess)

Processes metadata associated with the link.
dependencyInfo[]

object (DependencyInfo)

Describes how the target entity is dependent on the source entity.
depth

integer

Depth of the current link in the graph starting from 1.
location

string

The location where the LineageEvent that created the link is stored.

EntityReference

JSON representation 
{
  "fullyQualifiedName": string,
  "field": [
    string
  ]
}
Fields
fullyQualifiedName

string

Required. Fully Qualified Name (FQN) of the entity.
field[]

string

Optional. Field path within the entity. Each nesting level should be a separate value in the repeated field. The order matters. Must be empty for asset level lineage

For example to address "salary.net" subfield where "salary" is a column and "net" is a proto field two values in the field should be reported, the first is "salary" and the second is "net".

Each field length is limited to 500 characters. Maximum supported nesting level is 20.

LineageProcess

JSON representation 
{
  "process": {
    object (Process)
  }
}
Fields
process

object (Process)

Process that created the link.

Process

JSON representation 
{
  "name": string,
  "displayName": string,
  "attributes": {
    string: value,
    ...
  },
  "origin": {
    object (Origin)
  }
}
Fields
name

string

Immutable. The resource name of the lineage process. Format: projects/{project}/locations/{location}/processes/{process}. Can be specified or auto-assigned. {process} must be not longer than 200 characters and only contain characters in a set: a-zA-Z0-9_-:.
displayName

string

Optional. A human-readable name you can set to display in a user interface. Must be not longer than 200 characters and only contain UTF-8 letters or numbers, spaces or characters like _-:&.
attributes

map (key: string, value: value (Value format))

Optional. The attributes of the process. Should only be used for the purpose of non-semantic management (classifying, describing or labeling the process).

Up to 100 attributes are allowed.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
origin

object (Origin)

Optional. The origin of this process and its runs and lineage events.

AttributesEntry

JSON representation 
{
  "key": string,
  "value": value
}
Fields
key

string
value

value (Value format)

Value

JSON representation 
{

  // Union field kind can be only one of the following:
  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
  // End of list of possible types for union field kind.
}
Fields
Union field kind. The kind of value. kind can be only one of the following:
nullValue

null

Represents a JSON null.
numberValue

number

Represents a JSON number. Must not be NaN, Infinity or -Infinity, since those are not supported in JSON. This also cannot represent large Int64 values, since JSON format generally does not support them in its number type.
stringValue

string

Represents a JSON string.
boolValue

boolean

Represents a JSON boolean (true or false literal in JSON).
structValue

object (Struct format)

Represents a JSON object.
listValue

array (ListValue format)

Represents a JSON array.

Struct

JSON representation 
{
  "fields": {
    string: value,
    ...
  }
}
Fields
fields

map (key: string, value: value (Value format))

Unordered map of dynamically typed values.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

JSON representation 
{
  "key": string,
  "value": value
}
Fields
key

string
value

value (Value format)

ListValue

JSON representation 
{
  "values": [
    value
  ]
}
Fields
values[]

value (Value format)

Repeated field of dynamically typed values.

Origin

JSON representation 
{
  "sourceType": enum (SourceType),
  "name": string
}
Fields
sourceType

enum (SourceType)

Type of the source.

Use of a source_type other than CUSTOM for process creation or updating is highly discouraged. It might be restricted in the future without notice. There will be increase in cost if you use any of the source types other than CUSTOM.
name

string

If the source_type isn't CUSTOM, the value of this field should be a Google Cloud resource name of the system, which reports lineage. The project and location parts of the resource name must match the project and location of the lineage resource being created. Examples:

  • {source_type: COMPOSER, name: "projects/foo/locations/us/environments/bar"}
  • {source_type: BIGQUERY, name: "projects/foo/locations/eu"}
  • {source_type: CUSTOM, name: "myCustomIntegration"}

DependencyInfo

JSON representation 
{
  "dependencyType": enum (DependencyType)
}
Fields
dependencyType

enum (DependencyType)

The type of dependency.

NullValue

Represents a JSON null.

NullValue is a sentinel, using an enum with only one value to represent the null value for the Value type union.

A field of type NullValue with any value other than 0 is considered invalid. Most ProtoJSON serializers will emit a Value with a null_value set as a JSON null regardless of the integer value, and so will round trip to a 0 value.

Enums
NULL_VALUE Null value.

SourceType

Type of the source of a process.

Enums
SOURCE_TYPE_UNSPECIFIED Source is Unspecified
CUSTOM A custom source
BIGQUERY BigQuery
DATA_FUSION Data Fusion
COMPOSER Composer
LOOKER_STUDIO Looker Studio
DATAPROC Dataproc
VERTEX_AI Vertex AI
DATAFLOW Dataflow
LOOKER_CORE Looker Core

DependencyType

Type of dependency between entities.

Enums
DEPENDENCY_TYPE_UNSPECIFIED Dependency type unspecified.
EXACT_COPY Exact data copy without any change.
OTHER Other types of dependencies like filtering or grouping.

Tool Annotations

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌