Proporciona o detecta automáticamente un esquema

Cuando importas datos estructurados con la Google Cloud consola de, 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 fallará.

**Importante:** Si no proporcionas un esquema, la función de detección automática puede actualizarlo incorporando los campos recién detectados cuando importes datos nuevos. Si algún documento de los datos importados contiene campos nuevos que no son retrocompatibles con tu esquema original, no se importarán esos documentos.

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

Términos clave: En el contexto del esquema, los términos campo y propiedad se usan indistintamente.

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

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

• Detección y edición automáticas. Permite que Gemini Enterprise detecte automáticamente y sugiera un esquema inicial. Luego, puedes refinar 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 Google Cloud instrucciones de la consola para 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, sube tus datos según ese esquema.

  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 Importar 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. En función de 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.

Sugerencia: Asegúrate de que los documentos al comienzo de tu conjunto de datos sean de buena calidad, es decir, que se representen todos los campos clave. De esa manera, no tendrás que agregar ni editar campos más adelante.

Si Gemini Enterprise encuentra campos adicionales más adelante en la importación de datos, los importa y los agrega al esquema. Si deseas editar el esquema después de que se importen todos los datos, consulta Actualiza tu esquema.

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
    }
  }
}

Estos son algunos de los campos de este ejemplo de esquema:

• dynamic. Si dynamic se establece en el valor de cadena "true", cualquier propiedad nueva que se encuentre en los datos importados se agregará al esquema. Si dynamic se establece en "false", se ignorarán las propiedades nuevas que se encuentren en los datos importados ; las propiedades no se agregarán al esquema ni se importarán 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 importarán la propiedad y los datos de las calificaciones. Si dynamic es "false", no se importarán las propiedades rating, aunque sí title y description.

  El valor predeterminado es "true".

• datetime_detection. Si datetime_detection se establece en el valor booleano true, cuando se importen datos en formato de fecha y hora, el tipo de esquema se establecerá en datetime. Los formatos admitidos son RFC 3339 y 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 datatime_detection se establece en el valor booleano false, cuando se importen datos en formato de fecha y hora, el tipo de esquema se establecerá en string.

  El valor predeterminado es true.

• geolocation_detection. Si geolocation_detection se establece en el valor booleano true, cuando se importen datos en formato de geolocalización, el tipo de esquema se establecerá en geolocation. Los datos se detectan como geolocalización 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 importen datos en formato de geolocalización, el tipo de esquema se establecerá en object.

  El valor predeterminado es true.

• keyPropertyMapping. Es un campo que asigna palabras clave predefinidas a campos críticos de 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 keyPropertyValues. Por ejemplo, para un campo que llamaste my_title, puedes incluir un keyPropertyValues campo con un valor de title.

  Los campos marcados con keyPropertyMapping son indexables y se pueden buscar de forma predeterminada, pero no se pueden recuperar, completar ni categorizar en facetas dinámicas. Esto significa que no necesitas incluir los campos indexable o searchable con un campo keyPropertyValues para obtener el comportamiento predeterminado esperado.

  Nota: Las propiedades clave pueden mejorar la calidad de los resultados de la búsqueda y la precisión del autocompletado de la búsqueda. Si usas la detección automática de esquemas, las propiedades clave no se agregan automáticamente. Te recomendamos que uses el schemas.patch método para marcar los campos de datos como propiedades clave, en especial title, uri y description.

• type. Es el tipo del 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 mostrar en una respuesta de búsqueda. Se puede establecer para campos de tipo number, string, boolean, integer, datetime y geolocation. Se puede establecer un máximo de 50 campos como recuperables. Los campos definidos por el usuario y los campos keyPropertyValues no se pueden recuperar de forma predeterminada. Para que un campo recuperable, incluye "retrievable": true con el campo.

• indexable. Indica si este campo se puede filtrar, categorizar en facetas, potenciar o ordenar en el método servingConfigs.search. Se puede establecer para campos de tipo number, string, boolean, integer, datetime y geolocation. Se puede establecer un máximo de 50 campos como indexables. Los campos definidos por el usuario no son indexables de forma predeterminada, excepto los campos que contienen el campo keyPropertyMapping. Para que un campo sea indexable, incluye "indexable": true con el campo.

• dynamicFacetable. Indica que el campo se puede usar como faceta dinámica. Se puede establecer para campos de tipo number, string, boolean y integer. Para que un campo se pueda categorizar en facetas dinámicas, 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 que coincida con las consultas de texto no estructurado. Solo se puede establecer para campos de tipo string. Se puede establecer un máximo de 50 campos como aptos para la búsqueda. Los campos definidos por el usuario no se pueden buscar de forma predeterminada, excepto los campos que contienen el campo keyPropertyMapping. Para que un campo se pueda buscar, incluye "searchable": true con el campo.

• completable. Indica si este campo se puede mostrar como una sugerencia de autocompletado. Solo se puede establecer para campos de tipo string. Para que un campo se pueda completar, incluye "completable": true con el campo.

Nota: En el caso de los esquemas detectados automáticamente, los campos recién detectados son automáticamente indexables, se pueden buscar y recuperar, siempre que cumplan los requisitos de tipo y se mantengan dentro de los límites máximos.

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 y usa el Ejemplo de esquema 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: el ID del almacén de datos que deseas crear. Este ID solo puede contener letras en minúscula, dígitos, guiones bajos y guiones.
   • DATA_STORE_DISPLAY_NAME: 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 nuevo esquema JSON 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: el ID del almacén de datos.

   • JSON_SCHEMA_OBJECT: tu nuevo esquema JSON 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"
         }
       }
     }

     Ejemplo de comando y resultado

     curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema" -d '{
     "structSchema": {
     "$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"
     }
     }
     }
     }'
     
     {
     "name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema/operations/update-schema-10569824819404198922",
     "metadata": {
     "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.UpdateSchemaMetadata"
     }
     }
     

4. Opcional: Revisa el esquema siguiendo el procedimiento para ver una definición de esquema.

¿Qué sigue?

• Crea una app de búsqueda
• Obtén la definición de esquema para datos estructurados
• Actualiza un esquema para datos estructurados