Proporciona o detecta automáticamente un esquema

Cuando importas datos estructurados con la consola de Google Cloud , Gemini Enterprise detecta automáticamente el esquema. Puedes usar este esquema detectado automáticamente en tu motor o usar la API para proporcionar un esquema que indique la estructura de los datos.

Si proporcionas un esquema y, luego, lo actualizas con uno nuevo, este debe ser retrocompatible con el original. De lo contrario, la actualización del esquema falla.

Para obtener información de referencia sobre el esquema, consulta dataStores.schemas.

Enfoques para proporcionar el esquema de tu almacén de datos

Existen varios enfoques para determinar el esquema de los datos estructurados.

  • Detecta y edita automáticamente. Permite que Gemini Enterprise detecte y sugiera automáticamente un esquema inicial. Luego, define mejor el esquema a través de la interfaz de la consola. Google recomienda que, después de que se detecten automáticamente tus campos, asignes propiedades clave a todos los campos importantes.

    Este es el enfoque que usarás cuando sigas las instrucciones de la consola de Google Cloud para los datos estructurados en Crea un almacén de datos propios.

  • Proporciona el esquema como un objeto JSON. Proporciona el esquema a Gemini Enterprise como un objeto JSON. Debes haber preparado un objeto JSON correcto. Para ver un ejemplo de un objeto JSON, consulta Ejemplo de esquema como un objeto JSON. Después de crear el esquema, subes tus datos de acuerdo con él.

    Este es el enfoque que puedes usar cuando creas un almacén de datos a través de la API con un comando (o programa) curl. Por ejemplo, consulta Importa una vez desde BigQuery. Consulta también las siguientes instrucciones: Proporciona tu propio esquema.

Acerca de la detección y edición automáticas

Cuando comienzas a importar datos, Gemini Enterprise toma muestras de los primeros documentos que se importan. Según estos documentos, propone un esquema para los datos, que luego puedes revisar o editar.

Si los campos que deseas asignar a las propiedades clave no están presentes en los documentos de muestra, puedes agregarlos de forma manual cuando revises el esquema.

Si Gemini Enterprise encuentra campos adicionales más adelante en la importación de datos, los importará y los agregará al esquema. Si quieres editar el esquema después de que se hayan importado todos los datos, consulta Actualiza tu esquema.

Cuando Gemini Enterprise detecta automáticamente un esquema, configura de forma automática los siguientes parámetros de configuración de campo para los campos detectados, siempre que se mantengan dentro de los límites máximos de campos:

Tipo de campo Configuración predeterminada para los campos detectados automáticamente
string indexable, retrievable, searchable, dynamicFacetable
integer, number, boolean indexable, retrievable, dynamicFacetable
Cualquier otro tipo, excepto object (datetime, geolocation, array) indexable, retrievable
object Ninguno

Ejemplo de esquema como un objeto JSON

Puedes definir tu propio esquema con el formato de esquema JSON, que es un lenguaje declarativo de código abierto para definir, anotar y validar documentos JSON. Por ejemplo, esta es una anotación de esquema JSON válida:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "dynamic": "true",
  "datetime_detection": true,
  "geolocation_detection": true,
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title",
      "retrievable": true,
      "completable": true
    },
    "description": {
      "type": "string",
      "keyPropertyMapping": "description"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    },
    "brand": {
      "type": "string",
      "indexable": true,
      "dynamicFacetable": true
    },
    "location": {
      "type": "geolocation",
      "indexable": true,
      "retrievable": true
    },
    "creationDate": {
      "type": "datetime",
      "indexable": true,
      "retrievable": true
    },
    "isCurrent": {
      "type": "boolean",
      "indexable": true,
      "retrievable": true
    }
  }
}

Configuración de esquema de nivel superior

Los siguientes campos de nivel superior en el esquema JSON controlan cómo Gemini Enterprise detecta y agrega campos cuando se importan documentos:

  • dynamic. Si dynamic se establece en el valor de cadena "true", cualquier propiedad nueva que se encuentre en los datos importados se agrega al esquema. Si dynamic se establece en "false", se ignoran las propiedades nuevas que se encuentran en los datos importados; las propiedades no se agregan al esquema ni se importan los valores.

    Por ejemplo, un esquema tiene dos propiedades: title y description, y subes datos que contienen propiedades para title, description y rating. Si dynamic es "true", se importan la propiedad y los datos de las calificaciones. Si dynamic es "false", no se importan las propiedades rating, aunque sí se importan title y description.

    El valor predeterminado es "true".

  • datetime_detection. Si datetime_detection se establece en el valor booleano true, cuando se importan datos en formato de fecha y hora, el tipo de esquema se establece en datetime. Los formatos admitidos son RFC 3339 e ISO 8601.

    Por ejemplo:

    • 2024-08-05 08:30:00 UTC

    • 2024-08-05T08:30:00Z

    • 2024-08-05T01:30:00-07:00

    • 2024-08-05

    • 2024-08-05T08:30:00+00:00

    Si datetime_detection se establece en el valor booleano false, cuando se importan datos en formato de fecha y hora, el tipo de esquema se establece en string.

    El valor predeterminado es true.

  • geolocation_detection. Si geolocation_detection se establece en el valor booleano true, cuando se importan datos en formato de ubicación geográfica, el tipo de esquema se establece en geolocation. Los datos se detectan como ubicación geográfica si son un objeto que contiene un número de latitud y un número de longitud, o un objeto que contiene una cadena de dirección.

    Por ejemplo:

    • "myLocation": {"latitude":37.42, "longitude":-122.08}

    • "myLocation": {"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"}

    Si geolocation_detection se establece en el valor booleano false, cuando se importan datos en formato de ubicación geográfica, el tipo de esquema se establece en object.

    El valor predeterminado es true.

Configuración de campos a nivel de la propiedad

Cada campo dentro del objeto properties admite las siguientes anotaciones para definir su tipo de datos, la asignación de propiedades de clave y el comportamiento de búsqueda:

  • keyPropertyMapping: Es un campo que asigna palabras clave predefinidas a campos críticos en tus documentos, lo que ayuda a aclarar su significado semántico. Los valores incluyen title, description, uri y category. Ten en cuenta que el nombre del campo no necesita coincidir con el valor de keyPropertyValues. Por ejemplo, para un campo que llamaste my_title, puedes incluir un campo keyPropertyValues con un valor de title.

    Los campos con una anotación keyPropertyMapping usan parámetros de configuración predefinidos de indexable y searchable determinados por la propiedad de clave, y no son retrievable, completable ni dynamicFacetable de forma predeterminada. Debido a que indexable y searchable están predefinidos, no debes incluir anotaciones "indexable" o "searchable" explícitas en el mismo campo de tu esquema JSON, incluso con un valor de false. De lo contrario, la solicitud falla con un error INVALID_ARGUMENT: Key property FIELD_NAME should not contain searchable or indexable annotation.. De todas formas, puedes incluir "retrievable": true para que el campo asignado se devuelva en los resultados de la búsqueda.

  • type: Es el tipo de campo. Este es un valor de cadena que es datetime, geolocation o uno de los tipos primitivos (integer, boolean, object, array, number o string).

  • retrievable. Indica si este campo se puede devolver en una respuesta de búsqueda. Esto se puede configurar para los campos de tipo number, string, boolean, integer, datetime y geolocation. Se puede establecer un máximo de 50 campos como recuperables. Cuando proporcionas o actualizas de forma explícita un esquema JSON, los campos definidos por el usuario y los campos keyPropertyMapping se establecen de forma predeterminada en false para retrievable, a menos que configures de forma explícita "retrievable": true en la definición del esquema.

  • indexable. Indica si este campo se puede filtrar, clasificar, potenciar o ordenar en el método servingConfigs.search. Esto se puede configurar para los campos de tipo number, string, boolean, integer, datetime y geolocation. Se puede establecer un máximo de 50 campos como indexables. Cuando proporcionas o actualizas un esquema JSON de forma explícita, los campos definidos por el usuario se establecen de forma predeterminada en false para indexable (excepto los campos que contienen keyPropertyMapping), a menos que establezcas "indexable": true de forma explícita en la definición del esquema.

  • dynamicFacetable: Indica que el campo se puede usar como una faceta dinámica. Esto se puede configurar para los campos de tipo number, string, boolean y integer. Para que un campo sea dinámicamente clasificable, también debe ser indexable: incluye "dynamicFacetable": true y "indexable": true con el campo.

  • searchable. Indica si este campo se puede indexar de forma inversa para coincidir con consultas de texto no estructurado. Esto solo se puede configurar para campos de tipo string. Se puede establecer un máximo de 50 campos como aptos para búsquedas. Cuando proporcionas o actualizas un esquema JSON de forma explícita, los campos definidos por el usuario se establecen de forma predeterminada en false para searchable (excepto los campos que contienen keyPropertyMapping), a menos que configures "searchable": true de forma explícita en la definición del esquema.

  • completable: Indica si este campo se puede devolver como una sugerencia de autocompletar. Esto solo se puede establecer para los campos de tipo string. Para que un campo se pueda completar, incluye "completable": true con el campo.

Proporciona tu propio esquema como un objeto JSON

Para proporcionar tu propio esquema, crea un almacén de datos que contenga un esquema vacío y, luego, actualiza el esquema y proporciona tu esquema como un objeto JSON. Lleva a cabo los pasos siguientes:

  1. Prepara el esquema como un objeto JSON con el Esquema de ejemplo como un objeto JSON como guía.

  2. Crea un almacén de datos.

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID" \
    -d '{
      "displayName": "DATA_STORE_DISPLAY_NAME",
      "industryVertical": "INDUSTRY_VERTICAL"
    }'
    

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto.
    • DATA_STORE_ID: Es el ID del almacén de datos que deseas crear. Este ID solo puede contener letras minúsculas, dígitos, guiones bajos y guiones.
    • DATA_STORE_DISPLAY_NAME: Es el nombre visible del almacén de datos que deseas crear.
    • INDUSTRY_VERTICAL: GENERIC
  3. Usa el método de la API schemas.patch para proporcionar tu esquema JSON nuevo como un objeto JSON.

    curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/schemas/default_schema" \
    -d '{
      "structSchema": JSON_SCHEMA_OBJECT
    }'
    

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID de tu proyecto.
    • DATA_STORE_ID: Es el ID del almacén de datos.
    • JSON_SCHEMA_OBJECT: Es tu esquema JSON nuevo como un objeto JSON. Por ejemplo:

      {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "keyPropertyMapping": "title"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string",
              "keyPropertyMapping": "category"
            }
          },
          "uri": {
            "type": "string",
            "keyPropertyMapping": "uri"
          }
        }
      }
  4. Opcional: Revisa el esquema siguiendo el procedimiento Visualiza una definición de esquema.

¿Qué sigue?