MCP Tools Reference: dataform.googleapis.com

Tool: create_compilation_result

Create a new Dataform compilation result in a given Google Cloud project and location.

This tool compiles .sqlx files into executable SQL. Agents need to know that subsequent code changes aren't reflected in this result unless a new compilation is triggered.

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

Agents can validate the compiled SQL by inspecting CompilationResultAction resources and potentially using a BigQuery tool for a dry run.

A valid compilation result is required before triggering a manual workflow invocation using the create_workflow_invocation tool.

Prerequisite: Create a repository using the create_repository tool before calling the create_compilation_result tool.

The following sample demonstrate how to use curl to invoke the create_compilation_result 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_compilation_result",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

CreateCompilationResult request message.

CreateCompilationResultRequest

JSON representation 
{
  "parent": string,
  "compilationResult": {
    object (CompilationResult)
  }
}
Fields
parent

string

Required. The repository in which to create the compilation result. Must be in the format projects/*/locations/*/repositories/*.
compilationResult

object (CompilationResult)

Required. The compilation result to create.

CompilationResult

JSON representation 
{
  "name": string,
  "codeCompilationConfig": {
    object (CodeCompilationConfig)
  },
  "resolvedGitCommitSha": string,
  "dataformCoreVersion": string,
  "compilationErrors": [
    {
      object (CompilationError)
    }
  ],
  "dataEncryptionState": {
    object (DataEncryptionState)
  },
  "createTime": string,
  "privateResourceMetadata": {
    object (PrivateResourceMetadata)
  },
  "gcsRepositorySnapshotMetadata": {
    object (GcsRepositorySnapshotMetadata)
  },

  // Union field source can be only one of the following:
  "gitCommitish": string,
  "workspace": string,
  "releaseConfig": string
  // End of list of possible types for union field 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 compilation result's name.
codeCompilationConfig

object (CodeCompilationConfig)

Immutable. If set, fields of code_compilation_config override the default compilation settings that are specified in dataform.json.
resolvedGitCommitSha

string

Output only. The fully resolved Git commit SHA of the code that was compiled. Not set for compilation results whose source is a workspace.
dataformCoreVersion

string

Output only. The version of @dataform/core that was used for compilation.
compilationErrors[]

object (CompilationError)

Output only. Errors encountered during project compilation.
dataEncryptionState

object (DataEncryptionState)

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

string (Timestamp format)

Output only. The timestamp of when the compilation result was created.

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".
privateResourceMetadata

object (PrivateResourceMetadata)

Output only. Metadata indicating whether this resource is user-scoped. CompilationResult resource is user_scoped only if it is sourced from a workspace.
gcsRepositorySnapshotMetadata

object (GcsRepositorySnapshotMetadata)

Output only. Metadata about the repository snapshot used by scheduled notebooks.
Union field source. The source of the compilation result. source can be only one of the following:
gitCommitish

string

Immutable. Git commit/tag/branch name at which the repository should be compiled. Must exist in the remote repository. Examples: - a commit SHA: 12ade345 - a tag: tag1 - a branch name: branch1
workspace

string

Immutable. The name of the workspace to compile. Must be in the format projects/*/locations/*/repositories/*/workspaces/*.
releaseConfig

string

Immutable. The name of the release config to compile. Must be in the format projects/*/locations/*/repositories/*/releaseConfigs/*.

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.

CodeCompilationConfig

JSON representation 
{
  "defaultDatabase": string,
  "defaultSchema": string,
  "defaultLocation": string,
  "assertionSchema": string,
  "vars": {
    string: string,
    ...
  },
  "databaseSuffix": string,
  "schemaSuffix": string,
  "tablePrefix": string,
  "builtinAssertionNamePrefix": string,
  "defaultNotebookRuntimeOptions": {
    object (NotebookRuntimeOptions)
  },
  "pipelineConfig": {
    object (PipelineConfig)
  }
}
Fields
defaultDatabase

string

Optional. The default database (Google Cloud project ID).
defaultSchema

string

Optional. The default schema (BigQuery dataset ID).
defaultLocation

string

Optional. The default BigQuery location to use. Defaults to "US". See the BigQuery docs for a full list of locations: https://cloud.google.com/bigquery/docs/locations.
assertionSchema

string

Optional. The default schema (BigQuery dataset ID) for assertions.
vars

map (key: string, value: string)

Optional. User-defined variables that are made available to project code during compilation.

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

string

Optional. The suffix that should be appended to all database (Google Cloud project ID) names.
schemaSuffix

string

Optional. The suffix that should be appended to all schema (BigQuery dataset ID) names.
tablePrefix

string

Optional. The prefix that should be prepended to all table names.
builtinAssertionNamePrefix

string

Optional. The prefix to prepend to built-in assertion names.
defaultNotebookRuntimeOptions

object (NotebookRuntimeOptions)

Optional. The default notebook runtime options.
pipelineConfig

object (PipelineConfig)

Optional. The pipeline options which defines the pipeline type and path within the Git repository.

VarsEntry

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

string
value

string

NotebookRuntimeOptions

JSON representation 
{
  "aiPlatformNotebookRuntimeTemplate": string,

  // Union field execution_sink can be only one of the following:
  "gcsOutputBucket": string
  // End of list of possible types for union field execution_sink.

  // Union field repository_snapshot_storage can be only one of the following:
  "gcsRepositorySnapshotDestination": {
    object (GcsRepositorySnapshotDestination)
  }
  // End of list of possible types for union field repository_snapshot_storage.
}
Fields
aiPlatformNotebookRuntimeTemplate

string

Optional. The resource name of the Colab runtime template, from which a runtime is created for notebook executions. If not specified, a runtime is created with Colab's default specifications.
Union field execution_sink. The location to store the notebook execution result. execution_sink can be only one of the following:
gcsOutputBucket

string

Optional. The Google Cloud Storage location to upload the result to. Format: gs://bucket-name.
Union field repository_snapshot_storage. The destination of the snapshot of repository files to be available for read-only access inside a notebook runtime repository_snapshot_storage can be only one of the following:
gcsRepositorySnapshotDestination

object (GcsRepositorySnapshotDestination)

Optional. The Google Cloud Storage destination to upload the snapshot to. For empty URI it defaults to the provided gcs_output_bucket. Format: gs://bucket-name/path/.

GcsRepositorySnapshotDestination

JSON representation 
{
  "repositorySnapshotUri": string
}
Fields
repositorySnapshotUri

string

Optional. The Google Cloud Storage destination to upload the repository snapshot to. Format: gs://bucket-name/path/.

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.

CompilationError

JSON representation 
{
  "message": string,
  "stack": string,
  "path": string,
  "actionTarget": {
    object (Target)
  }
}
Fields
message

string

Output only. The error's top level message.
stack

string

Output only. The error's full stack trace.
path

string

Output only. The path of the file where this error occurred, if available, relative to the project root.
actionTarget

object (Target)

Output only. The identifier of the action where this error occurred, if available.

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.

DataEncryptionState

JSON representation 
{
  "kmsKeyVersionName": string
}
Fields
kmsKeyVersionName

string

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

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.

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.

GcsRepositorySnapshotMetadata

JSON representation 
{
  "repositorySnapshotUri": string,
  "crc32cChecksum": string,
  "generation": string
}
Fields
repositorySnapshotUri

string

Output only. The Google Cloud Storage URI of the repository snapshot.
crc32cChecksum

string

Output only. The crc32c checksum of the repository snapshot, big-endian base64 encoded.
generation

string (int64 format)

Output only. The generation number of the Cloud Storage object. See https://cloud.google.com/storage/docs/metadata#generation-number.

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 the result of compiling a Dataform project.

CompilationResult

JSON representation 
{
  "name": string,
  "codeCompilationConfig": {
    object (CodeCompilationConfig)
  },
  "resolvedGitCommitSha": string,
  "dataformCoreVersion": string,
  "compilationErrors": [
    {
      object (CompilationError)
    }
  ],
  "dataEncryptionState": {
    object (DataEncryptionState)
  },
  "createTime": string,
  "privateResourceMetadata": {
    object (PrivateResourceMetadata)
  },
  "gcsRepositorySnapshotMetadata": {
    object (GcsRepositorySnapshotMetadata)
  },

  // Union field source can be only one of the following:
  "gitCommitish": string,
  "workspace": string,
  "releaseConfig": string
  // End of list of possible types for union field 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 compilation result's name.
codeCompilationConfig

object (CodeCompilationConfig)

Immutable. If set, fields of code_compilation_config override the default compilation settings that are specified in dataform.json.
resolvedGitCommitSha

string

Output only. The fully resolved Git commit SHA of the code that was compiled. Not set for compilation results whose source is a workspace.
dataformCoreVersion

string

Output only. The version of @dataform/core that was used for compilation.
compilationErrors[]

object (CompilationError)

Output only. Errors encountered during project compilation.
dataEncryptionState

object (DataEncryptionState)

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

string (Timestamp format)

Output only. The timestamp of when the compilation result was created.

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".
privateResourceMetadata

object (PrivateResourceMetadata)

Output only. Metadata indicating whether this resource is user-scoped. CompilationResult resource is user_scoped only if it is sourced from a workspace.
gcsRepositorySnapshotMetadata

object (GcsRepositorySnapshotMetadata)

Output only. Metadata about the repository snapshot used by scheduled notebooks.
Union field source. The source of the compilation result. source can be only one of the following:
gitCommitish

string

Immutable. Git commit/tag/branch name at which the repository should be compiled. Must exist in the remote repository. Examples: - a commit SHA: 12ade345 - a tag: tag1 - a branch name: branch1
workspace

string

Immutable. The name of the workspace to compile. Must be in the format projects/*/locations/*/repositories/*/workspaces/*.
releaseConfig

string

Immutable. The name of the release config to compile. Must be in the format projects/*/locations/*/repositories/*/releaseConfigs/*.

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.

CodeCompilationConfig

JSON representation 
{
  "defaultDatabase": string,
  "defaultSchema": string,
  "defaultLocation": string,
  "assertionSchema": string,
  "vars": {
    string: string,
    ...
  },
  "databaseSuffix": string,
  "schemaSuffix": string,
  "tablePrefix": string,
  "builtinAssertionNamePrefix": string,
  "defaultNotebookRuntimeOptions": {
    object (NotebookRuntimeOptions)
  },
  "pipelineConfig": {
    object (PipelineConfig)
  }
}
Fields
defaultDatabase

string

Optional. The default database (Google Cloud project ID).
defaultSchema

string

Optional. The default schema (BigQuery dataset ID).
defaultLocation

string

Optional. The default BigQuery location to use. Defaults to "US". See the BigQuery docs for a full list of locations: https://cloud.google.com/bigquery/docs/locations.
assertionSchema

string

Optional. The default schema (BigQuery dataset ID) for assertions.
vars

map (key: string, value: string)

Optional. User-defined variables that are made available to project code during compilation.

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

string

Optional. The suffix that should be appended to all database (Google Cloud project ID) names.
schemaSuffix

string

Optional. The suffix that should be appended to all schema (BigQuery dataset ID) names.
tablePrefix

string

Optional. The prefix that should be prepended to all table names.
builtinAssertionNamePrefix

string

Optional. The prefix to prepend to built-in assertion names.
defaultNotebookRuntimeOptions

object (NotebookRuntimeOptions)

Optional. The default notebook runtime options.
pipelineConfig

object (PipelineConfig)

Optional. The pipeline options which defines the pipeline type and path within the Git repository.

VarsEntry

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

string
value

string

NotebookRuntimeOptions

JSON representation 
{
  "aiPlatformNotebookRuntimeTemplate": string,

  // Union field execution_sink can be only one of the following:
  "gcsOutputBucket": string
  // End of list of possible types for union field execution_sink.

  // Union field repository_snapshot_storage can be only one of the following:
  "gcsRepositorySnapshotDestination": {
    object (GcsRepositorySnapshotDestination)
  }
  // End of list of possible types for union field repository_snapshot_storage.
}
Fields
aiPlatformNotebookRuntimeTemplate

string

Optional. The resource name of the Colab runtime template, from which a runtime is created for notebook executions. If not specified, a runtime is created with Colab's default specifications.
Union field execution_sink. The location to store the notebook execution result. execution_sink can be only one of the following:
gcsOutputBucket

string

Optional. The Google Cloud Storage location to upload the result to. Format: gs://bucket-name.
Union field repository_snapshot_storage. The destination of the snapshot of repository files to be available for read-only access inside a notebook runtime repository_snapshot_storage can be only one of the following:
gcsRepositorySnapshotDestination

object (GcsRepositorySnapshotDestination)

Optional. The Google Cloud Storage destination to upload the snapshot to. For empty URI it defaults to the provided gcs_output_bucket. Format: gs://bucket-name/path/.

GcsRepositorySnapshotDestination

JSON representation 
{
  "repositorySnapshotUri": string
}
Fields
repositorySnapshotUri

string

Optional. The Google Cloud Storage destination to upload the repository snapshot to. Format: gs://bucket-name/path/.

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.

CompilationError

JSON representation 
{
  "message": string,
  "stack": string,
  "path": string,
  "actionTarget": {
    object (Target)
  }
}
Fields
message

string

Output only. The error's top level message.
stack

string

Output only. The error's full stack trace.
path

string

Output only. The path of the file where this error occurred, if available, relative to the project root.
actionTarget

object (Target)

Output only. The identifier of the action where this error occurred, if available.

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.

DataEncryptionState

JSON representation 
{
  "kmsKeyVersionName": string
}
Fields
kmsKeyVersionName

string

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

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.

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.

GcsRepositorySnapshotMetadata

JSON representation 
{
  "repositorySnapshotUri": string,
  "crc32cChecksum": string,
  "generation": string
}
Fields
repositorySnapshotUri

string

Output only. The Google Cloud Storage URI of the repository snapshot.
crc32cChecksum

string

Output only. The crc32c checksum of the repository snapshot, big-endian base64 encoded.
generation

string (int64 format)

Output only. The generation number of the Cloud Storage object. See https://cloud.google.com/storage/docs/metadata#generation-number.

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: ❌