MCP Tools Reference: dataform.googleapis.com

Tool: create_workflow_invocation

Create a new workflow invocation in a given Dataform repository.

The parent parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}.

Either the compilation_result or the workflow_config parameter value is required.

  • If using compilation_result, the parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/compilationResults/{compilation_result}.
  • If using workflow_config, the parameter value must be in the format projects/{project_id}/locations/{location}/repositories/{repository}/workflowConfigs/{workflow_config}.

Prerequisite: To trigger an invocation, you must first create either a compilation_result using the create_compilation_result tool or a workflow_config using the create_workflow_config tool. You can't trigger an invocation directly from raw repository code.

The workflow invocation must be created using a custom service account. You can specify the service account using the invocationConfig.serviceAccount field. The service account can't be the default Dataform service agent. The service account must have the necessary permissions to execute the workflow, and the user must be authorized to act as the selected service account. This authorization is typically granted through the Service Account User (roles/iam.serviceAccountUser) IAM role, which can be granted on the service account itself or on the project that contains it.

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

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

Input Schema

CreateWorkflowInvocation request message.

CreateWorkflowInvocationRequest

JSON representation 
{
  "parent": string,
  "workflowInvocation": {
    object (WorkflowInvocation)
  }
}
Fields
parent

string

Required. The repository in which to create the workflow invocation. Must be in the format projects/*/locations/*/repositories/*.
workflowInvocation

object (WorkflowInvocation)

Required. The workflow invocation resource to create.

WorkflowInvocation

JSON representation 
{
  "name": string,
  "invocationConfig": {
    object (InvocationConfig)
  },
  "state": enum (State),
  "invocationTiming": {
    object (Interval)
  },
  "resolvedCompilationResult": string,
  "dataEncryptionState": {
    object (DataEncryptionState)
  },
  "privateResourceMetadata": {
    object (PrivateResourceMetadata)
  },
  "pipelineConfig": {
    object (PipelineConfig)
  },

  // Union field compilation_source can be only one of the following:
  "compilationResult": string,
  "workflowConfig": string
  // End of list of possible types for union field compilation_source.

  // Union field _internal_metadata can be only one of the following:
  "internalMetadata": string
  // End of list of possible types for union field _internal_metadata.
}
Fields
name

string

Output only. The workflow invocation's name.
invocationConfig

object (InvocationConfig)

Immutable. If left unset, a default InvocationConfig will be used.
state

enum (State)

Output only. This workflow invocation's current state.
invocationTiming

object (Interval)

Output only. This workflow invocation's timing details.
resolvedCompilationResult

string

Output only. The resolved compilation result that was used to create this invocation. Will be in the format projects/*/locations/*/repositories/*/compilationResults/*.
dataEncryptionState

object (DataEncryptionState)

Output only. Only set if the repository has a KMS Key.
privateResourceMetadata

object (PrivateResourceMetadata)

Output only. Metadata indicating whether this resource is user-scoped. WorkflowInvocation resource is user_scoped only if it is sourced from a compilation result and the compilation result is user-scoped.
pipelineConfig

object (PipelineConfig)

Output only. The pipeline options which defines the pipeline type and path within the Git repository.
Union field compilation_source. The source of the compilation result to use for this invocation. compilation_source can be only one of the following:
compilationResult

string

Immutable. The name of the compilation result to use for this invocation. Must be in the format projects/*/locations/*/repositories/*/compilationResults/*.
workflowConfig

string

Immutable. The name of the workflow config to invoke. Must be in the format projects/*/locations/*/repositories/*/workflowConfigs/*.

Union field _internal_metadata.

_internal_metadata can be only one of the following:
internalMetadata

string

Output only. All the metadata information that is used internally to serve the resource. For example: timestamps, flags, status fields, etc. The format of this field is a JSON string.

InvocationConfig

JSON representation 
{
  "includedTargets": [
    {
      object (Target)
    }
  ],
  "includedTags": [
    string
  ],
  "transitiveDependenciesIncluded": boolean,
  "transitiveDependentsIncluded": boolean,
  "fullyRefreshIncrementalTablesEnabled": boolean,
  "serviceAccount": string,

  // Union field _query_priority can be only one of the following:
  "queryPriority": enum (QueryPriority)
  // End of list of possible types for union field _query_priority.
}
Fields
includedTargets[]

object (Target)

Optional. The set of action identifiers to include.
includedTags[]

string

Optional. The set of tags to include.
transitiveDependenciesIncluded

boolean

Optional. When set to true, transitive dependencies of included actions will be executed.
transitiveDependentsIncluded

boolean

Optional. When set to true, transitive dependents of included actions will be executed.
fullyRefreshIncrementalTablesEnabled

boolean

Optional. When set to true, any incremental tables will be fully refreshed.
serviceAccount

string

Optional. The service account to run workflow invocations under.

Union field _query_priority.

_query_priority can be only one of the following:
queryPriority

enum (QueryPriority)

Optional. Specifies the priority for query execution in BigQuery. More information can be found at https://cloud.google.com/bigquery/docs/running-queries#queries.

Target

JSON representation 
{
  "database": string,
  "schema": string,
  "name": string
}
Fields
database

string

Optional. The action's database (Google Cloud project ID) .
schema

string

Optional. The action's schema (BigQuery dataset ID), within database.
name

string

Optional. The action's name, within database and schema.

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.

DataEncryptionState

JSON representation 
{
  "kmsKeyVersionName": string
}
Fields
kmsKeyVersionName

string

Required. The KMS key version name with which data of a resource is encrypted.

PrivateResourceMetadata

JSON representation 
{
  "userScoped": boolean
}
Fields
userScoped

boolean

Output only. If true, this resource is user-scoped, meaning it is either a workspace or sourced from a workspace.

PipelineConfig

JSON representation 
{
  "pipelineType": enum (PipelineType),
  "path": string
}
Fields
pipelineType

enum (PipelineType)

Required. The type of the pipeline.
path

string

Required. The relative path within the Git repository where the pipeline is defined. For example, for a Dataform pipeline, it is a path to the folder where workflow_settings.yaml or dataform.json is located.

QueryPriority

Types of priority for query execution in BigQuery.

Enums
QUERY_PRIORITY_UNSPECIFIED Default value. This value is unused.
INTERACTIVE Query will be executed in BigQuery with interactive priority. More information can be found at https://cloud.google.com/bigquery/docs/running-queries#queries.
BATCH Query will be executed in BigQuery with batch priority. More information can be found at https://cloud.google.com/bigquery/docs/running-queries#batchqueries.

State

Represents the current state of a workflow invocation.

Enums
STATE_UNSPECIFIED Default value. This value is unused.
RUNNING The workflow invocation is currently running.
SUCCEEDED The workflow invocation succeeded. A terminal state.
CANCELLED The workflow invocation was cancelled. A terminal state.
FAILED The workflow invocation failed. A terminal state.
CANCELING The workflow invocation is being cancelled, but some actions are still running.

PipelineType

The type of the pipeline. This may be extended in the future. In case of UNSPECIFIED, the error will be thrown.

Enums
PIPELINE_TYPE_UNSPECIFIED Default value. This value is unused.
DATAFORM Regular Dataform pipeline.
SQL SQL single file asset.
NOTEBOOK Notebook single file asset.

Output Schema

Represents a single invocation of a compilation result.

WorkflowInvocation

JSON representation 
{
  "name": string,
  "invocationConfig": {
    object (InvocationConfig)
  },
  "state": enum (State),
  "invocationTiming": {
    object (Interval)
  },
  "resolvedCompilationResult": string,
  "dataEncryptionState": {
    object (DataEncryptionState)
  },
  "privateResourceMetadata": {
    object (PrivateResourceMetadata)
  },
  "pipelineConfig": {
    object (PipelineConfig)
  },

  // Union field compilation_source can be only one of the following:
  "compilationResult": string,
  "workflowConfig": string
  // End of list of possible types for union field compilation_source.

  // Union field _internal_metadata can be only one of the following:
  "internalMetadata": string
  // End of list of possible types for union field _internal_metadata.
}
Fields
name

string

Output only. The workflow invocation's name.
invocationConfig

object (InvocationConfig)

Immutable. If left unset, a default InvocationConfig will be used.
state

enum (State)

Output only. This workflow invocation's current state.
invocationTiming

object (Interval)

Output only. This workflow invocation's timing details.
resolvedCompilationResult

string

Output only. The resolved compilation result that was used to create this invocation. Will be in the format projects/*/locations/*/repositories/*/compilationResults/*.
dataEncryptionState

object (DataEncryptionState)

Output only. Only set if the repository has a KMS Key.
privateResourceMetadata

object (PrivateResourceMetadata)

Output only. Metadata indicating whether this resource is user-scoped. WorkflowInvocation resource is user_scoped only if it is sourced from a compilation result and the compilation result is user-scoped.
pipelineConfig

object (PipelineConfig)

Output only. The pipeline options which defines the pipeline type and path within the Git repository.
Union field compilation_source. The source of the compilation result to use for this invocation. compilation_source can be only one of the following:
compilationResult

string

Immutable. The name of the compilation result to use for this invocation. Must be in the format projects/*/locations/*/repositories/*/compilationResults/*.
workflowConfig

string

Immutable. The name of the workflow config to invoke. Must be in the format projects/*/locations/*/repositories/*/workflowConfigs/*.

Union field _internal_metadata.

_internal_metadata can be only one of the following:
internalMetadata

string

Output only. All the metadata information that is used internally to serve the resource. For example: timestamps, flags, status fields, etc. The format of this field is a JSON string.

InvocationConfig

JSON representation 
{
  "includedTargets": [
    {
      object (Target)
    }
  ],
  "includedTags": [
    string
  ],
  "transitiveDependenciesIncluded": boolean,
  "transitiveDependentsIncluded": boolean,
  "fullyRefreshIncrementalTablesEnabled": boolean,
  "serviceAccount": string,

  // Union field _query_priority can be only one of the following:
  "queryPriority": enum (QueryPriority)
  // End of list of possible types for union field _query_priority.
}
Fields
includedTargets[]

object (Target)

Optional. The set of action identifiers to include.
includedTags[]

string

Optional. The set of tags to include.
transitiveDependenciesIncluded

boolean

Optional. When set to true, transitive dependencies of included actions will be executed.
transitiveDependentsIncluded

boolean

Optional. When set to true, transitive dependents of included actions will be executed.
fullyRefreshIncrementalTablesEnabled

boolean

Optional. When set to true, any incremental tables will be fully refreshed.
serviceAccount

string

Optional. The service account to run workflow invocations under.

Union field _query_priority.

_query_priority can be only one of the following:
queryPriority

enum (QueryPriority)

Optional. Specifies the priority for query execution in BigQuery. More information can be found at https://cloud.google.com/bigquery/docs/running-queries#queries.

Target

JSON representation 
{
  "database": string,
  "schema": string,
  "name": string
}
Fields
database

string

Optional. The action's database (Google Cloud project ID) .
schema

string

Optional. The action's schema (BigQuery dataset ID), within database.
name

string

Optional. The action's name, within database and schema.

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.

DataEncryptionState

JSON representation 
{
  "kmsKeyVersionName": string
}
Fields
kmsKeyVersionName

string

Required. The KMS key version name with which data of a resource is encrypted.

PrivateResourceMetadata

JSON representation 
{
  "userScoped": boolean
}
Fields
userScoped

boolean

Output only. If true, this resource is user-scoped, meaning it is either a workspace or sourced from a workspace.

PipelineConfig

JSON representation 
{
  "pipelineType": enum (PipelineType),
  "path": string
}
Fields
pipelineType

enum (PipelineType)

Required. The type of the pipeline.
path

string

Required. The relative path within the Git repository where the pipeline is defined. For example, for a Dataform pipeline, it is a path to the folder where workflow_settings.yaml or dataform.json is located.

QueryPriority

Types of priority for query execution in BigQuery.

Enums
QUERY_PRIORITY_UNSPECIFIED Default value. This value is unused.
INTERACTIVE Query will be executed in BigQuery with interactive priority. More information can be found at https://cloud.google.com/bigquery/docs/running-queries#queries.
BATCH Query will be executed in BigQuery with batch priority. More information can be found at https://cloud.google.com/bigquery/docs/running-queries#batchqueries.

State

Represents the current state of a workflow invocation.

Enums
STATE_UNSPECIFIED Default value. This value is unused.
RUNNING The workflow invocation is currently running.
SUCCEEDED The workflow invocation succeeded. A terminal state.
CANCELLED The workflow invocation was cancelled. A terminal state.
FAILED The workflow invocation failed. A terminal state.
CANCELING The workflow invocation is being cancelled, but some actions are still running.

PipelineType

The type of the pipeline. This may be extended in the future. In case of UNSPECIFIED, the error will be thrown.

Enums
PIPELINE_TYPE_UNSPECIFIED Default value. This value is unused.
DATAFORM Regular Dataform pipeline.
SQL SQL single file asset.
NOTEBOOK Notebook single file asset.

Tool Annotations

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