Proporciona o detecta automáticamente un esquema

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

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.

  • Detección y edición automáticas. Permite que Agent Search 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 consola instrucciones de para datos estructurados en Crea un almacén de datos de búsqueda y Crea un almacén de datos de recomendaciones personalizado.

  • Proporciona el esquema como un objeto JSON. Proporciona el esquema a Agent Search 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.

  • Contenido multimedia: Proporciona tus datos en el esquema definido por Google. Si creas un almacén de datos para contenido multimedia, puedes usar el esquema predefinido de Google. Si eliges esta opción, se supone que estructuraste tu objeto JSON en el formato que se indica en Acerca de los documentos de contenido multimedia y el almacén de datos. De forma predeterminada, la detección automática agrega al esquema cualquier campo nuevo que encuentre durante la transferencia de datos.

    Este es el enfoque que usas cuando sigues las instrucciones de Crea una app y un almacén de datos de contenido multimedia. También es el enfoque de los instructivos Comienza a usar las recomendaciones de contenido multimedia y Comienza a usar la búsqueda de contenido multimedia, en los que los datos de muestra se proporcionan en el esquema predefinido de Google.

  • Contenido multimedia: Detección y edición automáticas. Asegúrate de incluir las propiedades de contenido multimedia obligatorias. Para los datos de contenido multimedia, puedes usar la detección automática para sugerir el esquema y editarlo para refinarlo. En tu objeto JSON, debes incluir campos que se puedan asignar a las propiedades clave de contenido multimedia: title, uri, category, media_duration y media_available_time.

    Este es el enfoque que usarás cuando importes datos de contenido multimedia a través de la Google Cloud consola si los datos de contenido multimedia no están en el esquema definido por Google.

  • Contenido multimedia: Proporciona tu propio esquema como un objeto JSON. Proporciona el esquema a Agent Search como un objeto JSON. Debes haber preparado un objeto JSON correcto. El esquema debe incluir campos que se puedan asignar a las propiedades clave de contenido multimedia: title, uri, category, media_duration y media_available_time.

    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 de contenido multimedia según ese esquema.

    Para este enfoque, usas la API a través de un comando (o programa) curl. Consulta las siguientes instrucciones: Proporciona tu propio esquema.

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

Cuando comienzas a importar datos, Agent Search 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 Agent Search 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
    },
    "runtime": {
      "type": "string",
      "keyPropertyMapping": "media_duration"
    },
    "releaseDate": {
      "type": "string",
      "keyPropertyMapping": "media_available_time"
    }
  }
}

Si defines un esquema de contenido multimedia, debes incluir campos que se puedan asignar a las propiedades clave de contenido multimedia. Estas propiedades clave se muestran en este ejemplo.

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 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 calificaciones. Si dynamic es "false", no se importan 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 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 datatime_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 geolocalización, el tipo de esquema se establece 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 importan datos en formato de geolocalización, el tipo de esquema se establece 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, category, update_time y create_time. No es necesario que el nombre de tu campo coincida con el valor keyPropertyValues. Por ejemplo, para un campo que llamaste my_title, puedes incluir un keyPropertyValues campo con un valor de title.

    En el caso de los almacenes de datos de búsqueda, 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.

    Las propiedades clave pueden mejorar la calidad de los resultados de la búsqueda y las recomendaciones, y la exactitud del autocompletado de la búsqueda. Si usas la detección automática de esquemas, no asigna automáticamente las propiedades clave y debes agregar la asignación de forma manual.

    Se requiere la asignación de un campo de documento a update_time (o create_time como alternativa) para el indicador de clasificación personalizado document_age. Para obtener más información sobre document_age, consulta Indicador estándar.

  • 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).

Los siguientes campos de propiedades solo se aplican a las apps de búsqueda:

  • retrievable. Indica si este campo se puede mostrar en una respuesta de búsqueda. Se puede configurar 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 configurar 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 configurar 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 configurar 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 configurar para campos de tipo string. Para que un campo se pueda completar, incluye "completable": true con el campo.

Además, el siguiente campo solo se aplica a las apps de recomendaciones:

  • recommendationsFilterable. Indica que el campo se puede usar en una expresión de filtro de recomendaciones. Para obtener información general sobre el filtrado de recomendaciones, consulta Filtra recomendaciones.

      ...
    "genres": {
    "type": "string",
    "recommendationsFilterable": true,
    ...
  },

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 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 Google Cloud proyecto
    • DATA_STORE_ID: el ID del almacén de datos de Agent Search 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 de Agent Search que deseas crear
    • INDUSTRY_VERTICAL: GENERIC o MEDIA

  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 Google Cloud proyecto
    • DATA_STORE_ID: el ID del almacén de datos de Agent Search

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

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

¿Qué sigue?