REST Resource: projects.locations.dataAgents

Resource: DataAgent

Message describing a DataAgent object.

JSON representation 
{
  "name": string,
  "displayName": string,
  "description": string,
  "labels": {
    string: string,
    ...
  },
  "createTime": string,
  "updateTime": string,
  "deleteTime": string,
  "purgeTime": string,

  // Union field type can be only one of the following:
  "dataAnalyticsAgent": {
    object (DataAnalyticsAgent)
  }
  // End of list of possible types for union field type.
  "kmsKey": string
}
Fields
name

string

Optional. Identifier. The unique resource name of a DataAgent. Format: projects/{project}/locations/{location}/dataAgents/{dataAgentId} {dataAgent} is the resource id and should be 63 characters or less and must match the format described in https://google.aip.dev/122#resource-id-segments

Example: projects/1234567890/locations/global/dataAgents/my-agent.

It is recommended to skip setting this field during agent creation as it will be inferred automatically and overwritten with the {parent}/dataAgents/{dataAgentId}.
displayName

string

Optional. User friendly display name.

  • Must be between 1-256 characters.
description

string

Optional. Description of the agent.

  • Must be between 1-1024 characters.
labels

map (key: string, value: string)

Optional. Labels to help users filter related agents. For example, "sales", "business", "etl", and so on. Note labels are used only for filtering and not for policies. See the labels documentation for more details on label usage.

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

string (Timestamp format)

Output only. The time when the data agent 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".
updateTime

string (Timestamp format)

Output only. The time when the data agent was last updated.

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

string (Timestamp format)

Output only. [Output only] The time the data agent was soft deleted.

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

string (Timestamp format)

Output only. Timestamp in UTC of when this data agent is considered expired. This is always provided on output, regardless of what was sent on input.

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".
Union field type. The type of the agent. Can be one of the following: * Data analytics agent. * Data engineering agent type can be only one of the following:
dataAnalyticsAgent

object (DataAnalyticsAgent)

Data analytics agent.
kmsKey

string

Optional. Customer managed encryption key (CMEK) to use for encrypting the DataAgent resources. Cloud KMS CryptoKeys must reside in the same location as the DataAgent. The expected format is projects/*/locations/*/keyRings/*/cryptoKeys/*.

DataAnalyticsAgent

Message describing a DataAnalyticsAgent object.

JSON representation 
{
  "stagingContext": {
    object (Context)
  },
  "publishedContext": {
    object (Context)
  },
  "lastPublishedContext": {
    object (Context)
  }
}
Fields
stagingContext

object (Context)

Optional. The staging context for the agent. This context is used to test and validate changes before publishing.
publishedContext

object (Context)

Optional. The published context for the agent. This context is used by the Chat API in production.
lastPublishedContext

object (Context)

Output only. The last published context for the agent. This is an output-only field populated by the system when the published context is updated. It is used to restore the agent to a previous state.

Context

A collection of context to apply to this conversation

JSON representation 
{
  "systemInstruction": string,
  "datasourceReferences": {
    object (DatasourceReferences)
  },
  "options": {
    object (ConversationOptions)
  },
  "exampleQueries": [
    {
      object (ExampleQuery)
    }
  ],
  "lookerGoldenQueries": [
    {
      object (LookerGoldenQuery)
    }
  ],
  "glossaryTerms": [
    {
      object (GlossaryTerm)
    }
  ],
  "schemaRelationships": [
    {
      object (SchemaRelationship)
    }
  ],
  "userFunctions": {
    object (UserFunctions)
  }
}
Fields
systemInstruction

string

Optional. The basic entry point for data owners creating domain knowledge for Agent.

Why: Business jargon (e.g., YTD revenue is calculated as…, Retirement Age is 65 in the USA, etc) and system instructions (e.g., answer like a Pirate) can help the model understand the business context around a user question.
datasourceReferences

object (DatasourceReferences)

Required. Data sources that are available for answering the question.
options

object (ConversationOptions)

Optional. Additional options for the conversation.
exampleQueries[]

object (ExampleQuery)

Optional. A list of example queries, providing examples of relevant and commonly used SQL queries and their corresponding natural language queries optionally present. Currently only used for BigQuery data sources and databases (alloydb, cloudsql, spanner) data sources.
lookerGoldenQueries[]

object (LookerGoldenQuery)

Optional. A list of golden queries, providing examples of relevant and commonly used Looker queries and their corresponding natural language queries optionally present. Only supported for Looker data sources.
glossaryTerms[]

object (GlossaryTerm)

Optional. Term definitions (currently, only user authored) Not supported for databases (alloydb, cloudsql, spanner) data sources.
schemaRelationships[]

object (SchemaRelationship)

Optional. Relationships between table schema, including referencing and referenced columns.
userFunctions

object (UserFunctions)

Optional. A collection of user functions to be included in context.

DatasourceReferences

A collection of references to datasources.

JSON representation 
{

  // Union field references can be only one of the following:
  "bq": {
    object (BigQueryTableReferences)
  },
  "studio": {
    object (StudioDatasourceReferences)
  },
  "looker": {
    object (LookerExploreReferences)
  }
  // End of list of possible types for union field references.
}
Fields
Union field references. The datasources to use. references can be only one of the following:
bq

object (BigQueryTableReferences)

References to BigQuery tables.
studio

object (StudioDatasourceReferences)

References to Looker Studio datasources.
looker

object (LookerExploreReferences)

References to Looker Explores.

BigQueryTableReferences

Message representing references to BigQuery tables and property graphs. At least one of tableReferences, propertyGraphReferences, or searchScope must be populated.

JSON representation 
{
  "tableReferences": [
    {
      object (BigQueryTableReference)
    }
  ]
}
Fields
tableReferences[]

object (BigQueryTableReference)

Optional. References to BigQuery tables.

BigQueryTableReference

Message representing a reference to a single BigQuery table.

JSON representation 
{
  "projectId": string,
  "datasetId": string,
  "tableId": string,
  "schema": {
    object (Schema)
  }
}
Fields
projectId

string

Required. The project that the table belongs to.
datasetId

string

Required. The dataset that the table belongs to.
tableId

string

Required. The table id.
schema

object (Schema)

Optional. The schema of the datasource.

Schema

The schema of a Datasource or QueryResult instance.

JSON representation 
{
  "fields": [
    {
      object (Field)
    }
  ],
  "description": string,
  "synonyms": [
    string
  ],
  "tags": [
    string
  ],
  "displayName": string,
  "filters": [
    {
      object (DataFilter)
    }
  ]
}
Fields
fields[]

object (Field)

Optional. The fields in the schema.
description

string

Optional. A textual description of the table's content and purpose. For example: "Contains information about customer orders in our e-commerce store." Currently only used for BigQuery data sources.
synonyms[]

string

Optional. A list of alternative names or synonyms that can be used to refer to the table. For example: ["sales", "orders", "purchases"]. Currently only used for BigQuery data sources.
tags[]

string

Optional. A list of tags or keywords associated with the table, used for categorization. For example: ["transaction", "revenue", "customer_data"]. Currently only used for BigQuery data sources.
displayName

string

Optional. Table displayName (same as label in cloud/data_analytics/anarres/data/looker/proto/model_explore.proto), not required, currently only Looker has this field.
filters[]

object (DataFilter)

Optional. The filters on the datasource's underlying data. Currently only used for Looker data sources.

Field

A field in a schema.

JSON representation 
{
  "name": string,
  "type": string,
  "description": string,
  "mode": string,
  "synonyms": [
    string
  ],
  "tags": [
    string
  ],
  "displayName": string,
  "subfields": [
    {
      object (Field)
    }
  ],
  "category": string,
  "valueFormat": string
}
Fields
name

string

Optional. The name of the field.
type

string

Optional. The type of the field.
description

string

Optional. A brief description of the field.
mode

string

Optional. The mode of the field (e.g., NULLABLE, REPEATED).
synonyms[]

string

Optional. A list of alternative names or synonyms that can be used to refer to this field. For example: ["id", "customerid", "cust_id"]. Currently only used for BigQuery data sources.
tags[]

string

Optional. A list of tags or keywords associated with the field, used for categorization. For example: ["identifier", "customer", "pii"]. Currently only used for BigQuery data sources.
displayName

string

Optional. Field displayName (same as label in
subfields[]

object (Field)

Optional. Recursive property for nested schema structures.
category

string

Optional. Field category, not required, currently only useful for Looker.
valueFormat

string

Optional. Looker only. Value format of the field. Ref: https://cloud.google.com/looker/docs/reference/param-field-value-format

DataFilter

A filter on a datasource's underlying data. Filter syntax documentation: https://cloud.google.com/looker/docs/filter-expressions

JSON representation 
{
  "field": string,
  "value": string,
  "type": enum (DataFilterType)
}
Fields
field

string

Optional. The field to filter on. For example: ["event_date", "customer_id", "product_category"]
value

string

Optional. The default value used for this filter if the filter is not overridden in a query. For example: ["after 2024-01-01", "123", "-fashion"]
type

enum (DataFilterType)

Optional. The type of filter present on a datasource, such as ALWAYS_FILTER.

DataFilterType

The type of filter present on a datasource, such as ALWAYS_FILTER.

Enums
DATA_FILTER_TYPE_UNSPECIFIED The filter type was not specified.
ALWAYS_FILTER A filter that the user configures, and any queries to the Explore will always apply this filter by default. Currently only used for Looker data sources.

StudioDatasourceReferences

Message representing references to Looker Studio datasources.

JSON representation 
{
  "studioReferences": [
    {
      object (StudioDatasourceReference)
    }
  ]
}
Fields
studioReferences[]

object (StudioDatasourceReference)

Optional. The references to the studio datasources.

StudioDatasourceReference

Message representing a reference to a single Looker Studio datasource.

JSON representation 
{
  "datasourceId": string
}
Fields
datasourceId

string

Required. The id of the datasource.

LookerExploreReferences

Message representing references to Looker explores.

JSON representation 
{
  "exploreReferences": [
    {
      object (LookerExploreReference)
    }
  ]
}
Fields
exploreReferences[]

object (LookerExploreReference)

Required. References to Looker explores.

LookerExploreReference

Message representing a reference to a single Looker explore.

JSON representation 
{
  "lookmlModel": string,
  "explore": string,
  "schema": {
    object (Schema)
  },

  // Union field instance can be only one of the following:
  "lookerInstanceUri": string,
  "privateLookerInstanceInfo": {
    object (PrivateLookerInstanceInfo)
  }
  // End of list of possible types for union field instance.
}
Fields
lookmlModel

string

Required. Looker model, as outlined in Major LookML structures. Name of the LookML model.
explore

string

Required. Looker Explore, as outlined in Major LookML structures. Name of the LookML Explore.
schema

object (Schema)

Optional. The schema of the datasource.
Union field instance. The instance of the Looker explore. instance can be only one of the following:
lookerInstanceUri

string

Required. The base url of the Looker instance.
privateLookerInstanceInfo

object (PrivateLookerInstanceInfo)

Private Looker instance info.

PrivateLookerInstanceInfo

Message representing a private Looker instance info required if the Looker instance is behind a private network.

JSON representation 
{
  "lookerInstanceId": string,
  "serviceDirectoryName": string
}
Fields
lookerInstanceId

string

The Looker instance id.
serviceDirectoryName

string

The service directory name of the Looker instance.

ConversationOptions

Options for the conversation.

JSON representation 
{
  "analysis": {
    object (AnalysisOptions)
  },
  "datasource": {
    object (DatasourceOptions)
  },
  "model": enum (Model)
}
Fields
analysis

object (AnalysisOptions)

Optional. Options for analysis.
datasource

object (DatasourceOptions)

Optional. Options for datasources.
model

enum (Model)

Optional. The model to use for the agent loop.

AnalysisOptions

Options for analysis.

JSON representation 
{
  "python": {
    object (Python)
  }
}
Fields
python

object (Python)

Optional. Options for Python analysis.

Python

Options for Python analysis.

JSON representation 
{
  "enabled": boolean
}
Fields
enabled

boolean

Optional. Whether to enable Python analysis. Defaults to false.

DatasourceOptions

Options for datasources configurations.

JSON representation 
{
  "bigQueryMaxBilledBytes": string
}
Fields
bigQueryMaxBilledBytes

string (Int64Value format)

Optional. This option applies to datasources that require BigQuery queries only. Limits the bytes billed for each BigQuery query job. Queries that will have bytes billed beyond this limit will fail (without incurring a charge). If unspecified, no limit will be applied.

Model

Allowed models for the agent/conversation.

Enums
MODEL_UNSPECIFIED No model specified. The model may be set on the chat request, or the default model will be used.
LATEST_GA_MODEL Use the most up-to-date non-preview model. This may constrain certain request level settings.

ExampleQuery

Example of relevant and commonly used SQL query and its corresponding natural language queries optionally present. Currently only used for BigQuery data sources.

JSON representation 
{
  "naturalLanguageQuestion": string,
  "parameters": [
    {
      object (QueryParameter)
    }
  ],

  // Union field query can be only one of the following:
  "sqlQuery": string
  // End of list of possible types for union field query.
}
Fields
naturalLanguageQuestion

string

Optional. A natural language question that a user might ask. For example: "How many orders were placed last month?"
parameters[]

object (QueryParameter)

Optional. The list of query parameters. Example: The parameterized SQL query "SELECT * FROM my_table WHERE id = @id" can be matched with any value of id.
Union field query. The SQL or Looker query that should be generated to answer the natural language query. query can be only one of the following:
sqlQuery

string

Optional. The SQL query that should be generated to answer the natural language question. For example: "SELECT COUNT(*) FROM orders WHERE order_date BETWEEN '2024-01-01' AND '2024-01-31'"

QueryParameter

A query parameter message represents a parameter that can be used to parameterize a SQL query.

JSON representation 
{
  "name": string,
  "description": string,
  "dataType": string
}
Fields
name

string

Required. The name of the parameter reference in the SQL query.
description

string

Optional. The description of the parameter that can be used by LLM to extract the parameter value from the user question.
dataType

string

Required. The data type of the parameter, e.g. "STRING", "INT64", "DATE", etc. For valid values, see the BigQuery documentation. This will be used to populate google.cloud.bigquery.v2.QueryParameterType.type.

LookerGoldenQuery

A golden query for Looker, including natural language questions and a corresponding Looker Query. Analogous to ExampleQuery.

JSON representation 
{
  "naturalLanguageQuestions": [
    string
  ],
  "lookerQuery": {
    object (LookerQuery)
  }
}
Fields
naturalLanguageQuestions[]

string

Optional. Natural language questions that a user might ask. For example: "How many orders were placed last month?"
lookerQuery

object (LookerQuery)

Optional. The Looker Query corresponding to the natural language questions.

LookerQuery

Looker Query Object Looker API documentation.

JSON representation 
{
  "model": string,
  "explore": string,
  "fields": [
    string
  ],
  "filters": [
    {
      object (Filter)
    }
  ],
  "sorts": [
    string
  ],
  "limit": string,
  "queryId": string,
  "clientId": string
}
Fields
model

string

Required. The LookML model used to generate the query.
explore

string

Required. The LookML explore used to generate the query.
fields[]

string

Optional. The fields to retrieve from the explore.
filters[]

object (Filter)

Optional. The filters to apply to the explore.
sorts[]

string

Optional. The sorts to apply to the explore.
limit

string

Optional. Limit in the query.
queryId

string

Optional. The primary identifier for the query resource in Looker, used for API operations. Maps to id (or slug) in the Looker API Query resource.
clientId

string

Optional. The short alphanumeric identifier for the query, used for share links and Explore URLs (e.g., in the qid parameter). Maps to clientId in the Looker API Query resource.

Filter

A Looker query filter.

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

string

Required. The field to filter on.
value

string

Optional. The value for the field to filter on. Optional so we can preserve the default value as an empty string, important to get a valid and working Looker Explore url.

GlossaryTerm

Definition of a term within a specific domain.

JSON representation 
{
  "displayName": string,
  "description": string,
  "labels": [
    string
  ]
}
Fields
displayName

string

Required. User friendly display name of the glossary term being defined. For example: "CTR", "conversion rate", "pending"
description

string

Required. The description or meaning of the term. For example: "Click-through rate", "The percentage of users who complete a desired action", "An order that is waiting to be processed."
labels[]

string

Optional. A list of general purpose labels associated to this term. For example: ["click rate", "clickthrough", "waiting"]

SchemaRelationship

The relationship between two tables, including referencing and referenced columns. This is a derived context retrieved from Dataplex Dataset Insights.

JSON representation 
{
  "leftSchemaPaths": {
    object (SchemaPaths)
  },
  "rightSchemaPaths": {
    object (SchemaPaths)
  },
  "sources": [
    enum (Source)
  ],
  "confidenceScore": number
}
Fields
leftSchemaPaths

object (SchemaPaths)

An ordered list of fields for the join from the first table. The size of this list must be the same as rightSchemaPaths. Each field at index i in this list must correspond to a field at the same index in the rightSchemaPaths list.
rightSchemaPaths

object (SchemaPaths)

An ordered list of fields for the join from the second table. The size of this list must be the same as leftSchemaPaths. Each field at index i in this list must correspond to a field at the same index in the leftSchemaPaths list.
sources[]

enum (Source)

Optional. Sources which generated the schema relation edge.
confidenceScore

number

Optional. A confidence score for the suggested relationship. Manually added edges have the highest confidence score.

SchemaPaths

Represents an ordered set of paths within the table schema.

JSON representation 
{
  "tableFqn": string,
  "paths": [
    string
  ]
}
Fields
tableFqn

string

The service-qualified full resource name of the table Ex: bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID
paths[]

string

The ordered list of paths within the table schema.

Source

Source which generated the schema relation edge.

Enums
SOURCE_UNSPECIFIED The source of the schema relationship is unspecified.
BIGQUERY_JOB_HISTORY The source of the schema relationship is BigQuery job history.
LLM_SUGGESTED The source of the schema relationship is LLM suggested.
BIGQUERY_TABLE_CONSTRAINTS The source of the schema relationship is BigQuery table constraints.

UserFunctions

A collection of user functions to be included in context.

JSON representation 
{
  "bqRoutines": [
    {
      object (BigQueryRoutine)
    }
  ]
}
Fields
bqRoutines[]

object (BigQueryRoutine)

A list of BigQuery routines to include in the context.

BigQueryRoutine

A reference to a BigQuery routine.

JSON representation 
{
  "routineReference": {
    object (BigQueryRoutineReference)
  },
  "description": string
}
Fields
routineReference

object (BigQueryRoutineReference)

The reference to the BigQuery routine.
description

string

User override or addition to description, to tell the agent when to use the UDF.

BigQueryRoutineReference

A reference to a BigQuery routine.

JSON representation 
{
  "projectId": string,
  "datasetId": string,
  "routineId": string
}
Fields
projectId

string

The project ID of the routine.
datasetId

string

The dataset ID of the routine.
routineId

string

The routine ID of the routine.

Methods

create

 Creates a new DataAgent in a given project and location.

createSync

 Creates a new DataAgent in a given project and location synchronously.

delete

 Deletes a single DataAgent.

deleteSync

 Deletes a single DataAgent synchronously.

get

 Gets details of a single DataAgent.

getIamPolicy

 Gets the IAM policy for DataAgent

list

 Lists DataAgents in a given project and location.

listAccessible

 Lists DataAgents that are accessible to the caller in a given project and location.

patch

 Updates the parameters of a single DataAgent.

setIamPolicy

 Sets the IAM policy for a DataAgent.

updateSync

 Updates the parameters of a single DataAgent synchronously.