Genera estadísticas de tablas

Las estadísticas de tablas de BigQuery te permiten comprender con rapidez la estructura y el contenido de las tablas estándar de BigQuery, las tablas externas de BigQuery y las tablas de BigLake sin escribir consultas complejas. Puedes generar consultas en SQL basadas en preguntas en lenguaje natural, lo que reduce el tiempo y el esfuerzo necesarios para escribir consultas de forma manual.

Para obtener una descripción general de las estadísticas de tablas y conjuntos de datos, consulta Descripción general de las estadísticas de datos.

Modos para generar estadísticas de datos de tablas

Cuando se generan estadísticas de tablas, BigQuery proporciona dos modos:

Modo Descripción Uso
Genera y publica (versión preliminar)

Conserva las estadísticas de tablas generadas en Knowledge Catalog como aspectos de metadatos. Debes tener los permisos necesarios para publicar. Cuando usas Generar y publicar, se realizan las siguientes acciones:

  • Almacena descripciones de tablas y columnas en Knowledge Catalog.
  • Captura las consultas y preguntas sugeridas como aspectos reutilizables.
  • Hace que las estadísticas publicadas sean accesibles para todos los usuarios que tengan el acceso adecuado a Knowledge Catalog, lo que garantiza el conocimiento compartido de la organización.
  • Te permite editar y guardar descripciones directamente en Knowledge Catalog.

Usa este modo para la documentación de datos de toda la empresa que persiste y es reutilizable, o cuando crees flujos de trabajo de administración basados en catálogos.
Generar sin publicar

Crea estadísticas de tablas, como descripciones, preguntas en lenguaje natural y consultas en SQL, a pedido. Generar sin publicar no publica estadísticas en Knowledge Catalog.

Usa este modo para realizar exploraciones rápidas y ad hoc, y evitar desordenar el catálogo.

Antes de comenzar

Las estadísticas de datos se generan con Gemini en BigQuery. Para comenzar a generar estadísticas, primero debes configurar Gemini en BigQuery.

Habilita las APIs

Para usar las estadísticas de datos, habilita las siguientes APIs en tu proyecto: API de Dataplex, API de BigQuery y API de Gemini para Google Cloud.

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

Habilitar las API

Para obtener más información para habilitar la API de Gemini para Google Cloud, consulta Habilita la API de Gemini para Google Cloud en un proyecto de Google Cloud .

Roles y permisos

Para crear, administrar y recuperar estadísticas de datos, pídele a tu administrador que te otorgue los siguientes roles de Identity and Access Management (IAM):

Para obtener acceso de solo lectura a las estadísticas generadas, pídele a tu administrador que te otorgue el siguiente rol de IAM:

Para publicar estadísticas de datos en Knowledge Catalog, pídele a tu administrador que te otorgue los siguientes roles de IAM en el recurso:

Para habilitar las APIs, pídele a tu administrador que te otorgue el siguiente rol de IAM:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido. Para ver los permisos exactos que se requieren para generar estadísticas, expande la sección Permisos requeridos:

Permisos necesarios

  • bigquery.jobs.create
  • bigquery.tables.get
  • bigquery.tables.getData
  • dataplex.datascans.create
  • dataplex.datascans.get
  • dataplex.datascans.getData
  • dataplex.datascans.run

Genera estadísticas para una tabla de BigQuery

Para generar estadísticas de las tablas de BigQuery, puedes usar la consola deGoogle Cloud o el tipo de análisis de DATA_DOCUMENTATION que admite la API de DataScans de Knowledge Catalog. Estos análisis generan metadatos, consultas en SQL para la exploración de datos, descripciones de esquemas y resúmenes a nivel de tabla.

Console

Para generar estadísticas para una tabla de BigQuery, debes acceder a la entrada de la tabla en BigQuery mediante BigQuery Studio.

  1. En la consola de Google Cloud , ve a BigQuery Studio.

    Ir a BigQuery Studio

  2. En el panel Explorador, selecciona el proyecto, el conjunto de datos y, luego, la tabla para la que deseas generar estadísticas.

  3. Haz clic en la pestaña Estadísticas.

    Si la pestaña está vacía, significa que aún no se generaron estadísticas para esta tabla.

  4. Para generar estadísticas, haz clic en Generar.

  5. Selecciona la condición de publicación:

    • Para generar y adjuntar de forma permanente estadísticas al recurso como aspectos de metadatos, activa el botón de activación Condición de publicación. Esto hace que las estadísticas se puedan indexar, buscar y ver para otros usuarios de tu organización.

    • Para generar y ver estadísticas de forma temporal durante tu sesión actual, desactiva el botón de activación Publicar condición.

    Para obtener más información sobre las diferencias entre los modos Generar y publicar y Generar sin publicar, consulta Modos para generar estadísticas de datos.

  6. Opcional: En el campo Instrucciones personalizadas, proporciona orientación y contexto del dominio para personalizar la forma en que Gemini genera estadísticas.

    Por ejemplo, puedes aplicar convenciones de nombres, especificar definiciones empresariales o describir claves de unión:

    LANGUAGE: Always write column descriptions in uppercase.

DOMAIN_CONTEXT:
- This dataset supports the Order-to-Cash process for the EMEA commercial
  sales team.
- Primary consumers are finance analysts and regional sales managers, not
  engineers.

RELATIONSHIPS:
- returns.order_item_id → order_items.id (one-to-one; use LEFT JOIN to
  preserve unreturned items)

  7. Selecciona una región para generar estadísticas y haz clic en Generar.

    Las estadísticas tardan unos minutos en propagarse.

    Si hay resultados publicados de la creación de perfiles de datos para la tabla, se usan para generar estadísticas. De lo contrario, las estadísticas se generan en función de los nombres y las descripciones de las columnas. Para obtener más información, consulta Prácticas recomendadas para generar estadísticas de datos.

  8. En la pestaña Estadísticas, explora las preguntas en lenguaje natural generadas.

  9. Para ver la consulta en SQL que responde una pregunta, haz clic en ella.

  10. Para abrir una consulta en BigQuery, haz clic en Copiar en la consulta.

  11. Para hacer preguntas de seguimiento, haz lo siguiente:

    1. Haz clic en Haz otra pregunta. La consulta se abrirá en un nuevo lienzo de datos.

    2. Haz clic en Ejecutar y, luego, en Consultar estos resultados.

    3. Para hacer una pregunta de seguimiento, ingresa una instrucción en el campo de instrucción Lenguaje natural o edita el SQL en el editor de consultas.

  12. Para generar un conjunto de consultas nuevo, haz clic en Generar estadísticas y vuelve a activar la canalización.

Después de generar estadísticas para una tabla, cualquier persona que tenga el permiso dataplex.datascans.getData y acceso a la tabla puede ver esas estadísticas.

REST

Para generar estadísticas de forma programática, usa la API de DataScans de Knowledge Catalog. Para hacerlo, sigue los pasos que se indican a continuación:

  1. Opcional: Crea un análisis de perfil de datos para la tabla
  2. Generar un análisis de datos de documentación de datos para la tabla de BigQuery
  3. Verifica el estado del escáner de documentos
  4. Publica los resultados del análisis de la documentación de datos en la tabla de BigQuery

Opcional: Crea un análisis de perfil de datos para la tabla

La presencia de análisis de perfiles de datos reduce las alucinaciones y las aproximaciones de Gemini, ya que fundamentan el resultado en valores reales presentes en los datos.

Para crear y ejecutar un análisis de perfil de datos, sigue estos pasos:

  1. Crea un análisis de perfil de datos con el método dataScans.create.

  2. Ejecuta el análisis del perfil de datos con el método dataScans.run. Espera a que se complete la ejecución.

  3. Publica los resultados del análisis en la tabla de BigQuery adjuntando las siguientes etiquetas de generación de perfiles de datos a la tabla:

    • dataplex-dp-published-scan:DATASCAN_ID
    • dataplex-dp-published-project:PROJECT_ID
    • dataplex-dp-published-location:LOCATION

    Para obtener más información, consulta Agrega etiquetas a tablas y vistas.

Genera un análisis de datos de documentación de datos para la tabla de BigQuery

Puedes elegir entre ejecutar un análisis administrado estándar o un análisis único optimizado.

Opción A: Análisis administrado estándar (crear y ejecutar)

Usa este método si quieres administrar el recurso de análisis con el tiempo.

  1. Crea un análisis de datos de documentación de datos con el método dataScans.create.

Puedes personalizar el alcance de la generación para incluir el esquema, las descripciones, las consultas o una combinación con el parámetro generation_scopes. De manera opcional, puedes publicar estas estadísticas en Knowledge Catalog si configuras el parámetro catalogPublishingEnabled como true.

  • Para generar esquemas, descripciones de tablas y consultas en SQL, deja data_documentation_spec vacío o establece generation_scopes en ALL. Por ejemplo:

      gcurl -X POST \
  https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
  dataScans?dataScanId=DATASCAN_ID \
  -d '{
    "data": {
      "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/\
  datasets/DATASET_ID/tables/TABLE_ID"
    },
    "executionSpec": {
      "trigger": { "onDemand": {} }
    },
    "type": "DATA_DOCUMENTATION",
    "dataDocumentationSpec": {
      "generationScopes": "ALL"
      "catalogPublishingEnabled": true
    }
  }'

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID de tu proyecto de Google Cloud en el que reside el conjunto de datos.
    • LOCATION: la región en la que se ejecuta el análisis de datos
    • DATASCAN_ID: Es un nombre único que proporcionas para este análisis.
    • DATASET_ID: el ID del conjunto de datos de BigQuery que se analiza
    • TABLE_ID: el ID de la tabla de BigQuery que se analiza

  • Para generar el esquema, las descripciones de las tablas y las descripciones de las columnas, sin consultas en SQL, establece generation_scopes en TABLE_AND_COLUMN_DESCRIPTIONS. Por ejemplo:

      gcurl -X POST \
  https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
  dataScans?dataScanId=DATASCAN_ID \
  -d '{
    "data": {
      "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/\
  datasets/DATASET_ID/tables/TABLE_ID"
    },
    "executionSpec": {
      "trigger": { "onDemand": {} }
    },
    "type": "DATA_DOCUMENTATION",
    "dataDocumentationSpec": {
      "generationScopes": "TABLE_AND_COLUMN_DESCRIPTIONS"
      "catalogPublishingEnabled": true
    }
  }'

  • Para generar consultas en SQL sin descripciones, establece generation_scopes en SQL_QUERIES. Por ejemplo:

      gcurl -X POST \
  https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
  dataScans?dataScanId=DATASCAN_ID \
  -d '{
    "data": {
      "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/\
  datasets/DATASET_ID/tables/TABLE_ID"
    },
    "executionSpec": {
      "trigger": { "onDemand": {} }
    },
    "type": "DATA_DOCUMENTATION",
    "dataDocumentationSpec": {
      "generationScopes": "SQL_QUERIES"
      "catalogPublishingEnabled": true
    }
  }'

  1. Inicia el trabajo de análisis de documentación de datos con el método dataScans.run.

    Por ejemplo:

    gcurl -X POST \
https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
dataScans/DATASCAN_ID:run

    Esta solicitud devuelve un ID de tarea único junto con el estado inicial.

Opción B: Análisis único (simplificado)

Usa este método para iniciar y completar un análisis en una sola llamada a la API. Este método elimina la necesidad de llamar al método run por separado y permite borrar automáticamente el recurso de análisis con la funcionalidad de tiempo de actividad (TTL).

Crea y activa el análisis con el método dataScans.create. Por ejemplo:

gcurl -X POST \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans?\
dataScanId=DATASCAN_ID" \
-d '{
  "data": {
    "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/\
    tables/TABLE_ID"
  },
  "type": "DATA_DOCUMENTATION",
  "dataDocumentationSpec": {
    "generationScopes": "ALL",
    "catalogPublishingEnabled": true
  }
  "executionSpec": {
    "trigger": {
      "one_time": {
        "ttl_after_scan_completion": { "seconds": TTL_TIME }
      }
    }
  }
}'

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID de tu proyecto de Google Cloud en el que reside el conjunto de datos.
  • LOCATION: la región en la que se ejecuta el análisis de datos
  • DATASCAN_ID: Es un nombre único que proporcionas para este análisis.
  • DATASET_ID: el ID del conjunto de datos de BigQuery que se analiza
  • TABLE_ID: Es el ID de la tabla de BigQuery que se analiza.
  • TTL_TIME: Es la duración en segundos después de la cual el recurso de análisis se debe borrar de forma automática (por ejemplo, 3600 para una hora).

Verifica el estado del análisis de la documentación de datos

Verifica que se haya completado la ejecución del trabajo de análisis con el método dataScans.get.

Usa el ID de trabajo para recuperar el estado del trabajo. Por ejemplo:

gcurl -X GET https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans/DATASCAN_ID/jobs/JOB_ID

El trabajo se completa cuando el estado es SUCCEEDED o FAILURE.

Publica los resultados del análisis de documentación de datos en la tabla de BigQuery

Para publicar los resultados del análisis en la tabla de BigQuery, adjunta las siguientes etiquetas de documentación de datos a la tabla:

  • dataplex-data-documentation-published-scan:DATASCAN_ID
  • dataplex-data-documentation-published-project:PROJECT_ID
  • dataplex-data-documentation-published-location:LOCATION

Genera estadísticas para una tabla externa de BigQuery

Las estadísticas de datos de BigQuery admiten la generación de estadísticas para tablas externas de BigQuery con datos en Cloud Storage. Tú y la cuenta de servicio de Knowledge Catalog para el proyecto actual deben tener el rol de visualizador de objetos de Storage (roles/storage.objectViewer) en el bucket de Cloud Storage que contiene los datos. Para obtener más información, consulta Agrega una principal a una política a nivel del bucket.

A fin de generar estadísticas para una tabla externa de BigQuery, sigue las instrucciones descritas en la sección Genera estadísticas para una tabla de BigQuery de este documento.

Genera estadísticas para una tabla de BigLake

Para generar estadísticas para una tabla de BigLake, sigue estos pasos:

  1. Habilita la API de conexión de BigQuery en tu proyecto.

    Habilita la API de conexión de BigQuery

  2. Crea una conexión de BigQuery. Para obtener más información, consulta Administra conexiones.

  3. Otórgale el rol de IAM de visualizador de objetos de almacenamiento (roles/storage.objectViewer) a la cuenta de servicio correspondiente a la conexión de BigQuery que creaste.

    Puedes recuperar el ID de la cuenta de servicio desde los detalles de conexión.

  4. Para generar estadísticas, sigue las instrucciones descritas en la sección Genera estadísticas para una tabla de BigQuery de este documento.

Genera descripciones de tablas y columnas

Gemini en BigQuery genera automáticamente descripciones de tablas y columnas cuando generas estadísticas de datos. Puedes editar estas descripciones según sea necesario y, luego, guardarlas en los metadatos de la tabla. Las descripciones guardadas se usan para generar estadísticas futuras.

Controla el idioma de generación

Puedes guiar a Gemini para que genere descripciones de tablas y columnas en un idioma específico. Para ello, usa el campo Instrucción personalizada para agregar una directiva breve (por ejemplo, "Genera descripciones de tablas y columnas en francés") a la descripción existente de tu tabla antes de generar las estadísticas de datos.

Cuando generas estadísticas, Gemini interpreta estas instrucciones y produce los metadatos en el idioma solicitado. Este mecanismo funciona porque Gemini usa las descripciones de tablas existentes como contexto cuando genera descripciones nuevas.

Para obtener una lista de los idiomas admitidos, consulta Compatibilidad con idiomas de Gemini.

Generar descripciones

Para generar descripciones de tablas y columnas, sigue estos pasos:

  1. Genera estadísticas siguiendo las instrucciones que se describen en la sección pertinente de este documento:

  2. Haz clic en la pestaña Esquema.

  3. Haz clic en Ver descripciones de columnas.

    Se muestran la descripción de la tabla y las descripciones de las columnas que se generaron.

  4. Para editar y guardar la descripción de la tabla generada, haz lo siguiente:

    1. En la sección Descripción de la tabla, haz clic en Guardar en los detalles.

    2. Para reemplazar la descripción actual por la generada, haz clic en Copiar la descripción sugerida.

    3. Edita la descripción de la tabla según sea necesario y, luego, haz clic en Guardar en los detalles.

      La descripción de la tabla se actualiza de inmediato.

  5. Para editar y guardar las descripciones de columnas generadas, haz lo siguiente:

    1. En la sección Descripciones de columnas, haz clic en Guardar en el esquema.

      Las descripciones de las columnas que se generaron se propagan en el campo Descripción nueva de cada columna.

    2. Edita las descripciones de las columnas según sea necesario y, luego, haz clic en Guardar.

      Las descripciones de las columnas se actualizan de inmediato.

  6. Para cerrar el panel de vista previa, haz clic en Cerrar.

Prácticas recomendadas para generar estadísticas de datos

Para mejorar la precisión de las estadísticas generadas, sigue estas recomendaciones:

  • Proporciona descripciones exhaustivas. Asegúrate de que las tablas y las columnas del conjunto de datos tengan descripciones claras y detalladas.

  • Fundamenta las estadísticas con la generación de perfiles. Si las descripciones no están disponibles, asegúrate de que un análisis de perfil esté vinculado a cada tabla del conjunto de datos para ayudar a fundamentar las estadísticas generadas.

  • Define reglas de forma explícita. Incluye cualquier relación o lógica empresarial que use el módulo de estadísticas para influir en la generación de relaciones dentro de la descripción de la tabla correspondiente.

Fundamenta las estadísticas en los resultados de la creación de perfiles de datos

En la IA generativa, los fundamentos son la capacidad de conectar el resultado del modelo con fuentes de información verificables. Puedes fundamentar las estadísticas de tablas generadas con los resultados de la creación de perfiles de datos. La creación de perfiles de datos analiza las columnas de tus tablas de BigQuery y, luego, identifica características estadísticas comunes, como los valores de datos típicos y la distribución de datos.

Cuando creas un análisis del perfil de datos para una tabla, puedes elegir publicar los resultados del análisis en las páginas de BigQuery y Knowledge Catalog en la consola de Google Cloud . Las estadísticas usan los resultados de la generación de perfiles de datos para crear consultas más precisas y pertinentes con las siguientes acciones:

  1. Analiza los resultados de la generación de perfiles de datos para identificar patrones, tendencias o valores atípicos interesantes en los datos.

  2. Generar consultas que se centren en estos patrones, tendencias o valores atípicos para descubrir estadísticas

  3. Valida las consultas generadas con los resultados de la generación de perfiles de datos para garantizar que las consultas muestren resultados significativos.

Sin los análisis del perfil de datos, sucede lo siguiente:

  • Es más probable que las consultas generadas incluyan cláusulas imprecisas o produzcan resultados sin sentido.

  • Las descripciones de las columnas generadas se basan solo en el nombre de la columna.

Asegúrate de que el análisis del perfil de datos de tu tabla esté actualizado y de que los resultados se publiquen en BigQuery.

Puedes ajustar la configuración de la generación de perfiles de datos para aumentar el tamaño de la muestra y filtrar filas y columnas. Después de ejecutar un análisis del perfil de datos nuevo, vuelve a generar las estadísticas.

La calidad de las estadísticas del conjunto de datos también mejora de forma significativa si las tablas del conjunto de datos tienen resultados de generación de perfiles de datos.

Agrega una descripción de la tabla

Las descripciones detalladas de las tablas que describen lo que quieres analizar en tu tabla pueden ayudar a Gemini en BigQuery a producir estadísticas más pertinentes para las estadísticas de tablas y conjuntos de datos. Después de agregar una descripción de la tabla, vuelve a generar las estadísticas.

Por ejemplo, puedes agregar la siguiente descripción a una tabla telco_churn, como la que se usa en Ejemplo de estadísticas de datos de tablas:

This table tracks customer churn data, including subscription details, tenure,
and service usage, to predict customer churn behavior.

Si guardas la descripción de la tabla que genera Gemini, esa descripción se usará para generar estadísticas futuras.

Agrega una descripción de la columna

Las descripciones de columnas que explican qué es cada columna o cómo se relaciona una columna con otra pueden mejorar la calidad de tus estadísticas para las estadísticas de tablas y conjuntos de datos. Después de actualizar las descripciones de las columnas en tu tabla, vuelve a generar las estadísticas.

Por ejemplo, puedes agregar las siguientes descripciones a columnas específicas de una tabla telco_churn, como la que se usa en Ejemplo de estadísticas de datos de tablas:

En la columna tenure, haz lo siguiente:

The number of months the customer has been with the service.

En la columna churn, haz lo siguiente:

Whether the customer has stopped using the service. TRUE indicates the customer
no longer uses the service, FALSE indicates the customer is active.

Si guardas las descripciones de columnas que genera Gemini, esas descripciones se usarán para generar estadísticas futuras.

Administra las estadísticas generadas

Después de generar estadísticas para una tabla, puedes administrarlas, actualizarlas o borrarlas en Knowledge Catalog. Para obtener más información, consulta Administra las estadísticas de tablas.

¿Qué sigue?