Crea y registra un esquema

Un esquema de Google Cloud Search es una estructura JSON que define objetos, propiedades y opciones para indexar y consultar datos. Tu conector de contenido usa el esquema registrado para estructurar y, luego, indexar los datos del repositorio.

Para crear un esquema, debes proporcionar un objeto de esquema JSON a la API. Debes registrar un esquema para cada repositorio antes de indexar los datos.

Nota: No necesitas un esquema para los datos no estructurados, como los sistemas básicos de archivos compartidos sin tipos de archivo predeterminados. También puedes usar el SDK para crear objetos de esquema.

En este documento, se explican los conceptos básicos de la creación de esquemas. Para optimizar la experiencia de búsqueda, consulta Mejora la calidad de la búsqueda.

Crea un esquema

Sigue estos pasos para crear tu esquema de Cloud Search:

1. Identifica el comportamiento esperado del usuario
2. Inicializa una fuente de datos
3. Define tus objetos
4. Define las propiedades de los objetos
5. Registra tu esquema
6. Indexa tus datos
7. Prueba tu esquema
8. Ajusta tu esquema

Nota: En este documento, se usa un esquema hipotético de base de datos de películas. Consulta schema.json para ver el ejemplo completo.

Identifica el comportamiento esperado del usuario

Prever cómo buscan los usuarios ayuda a definir tu estrategia de esquema. En el caso de una base de datos de películas, los usuarios pueden buscar "películas protagonizadas por Robert Redford". Tu esquema debe admitir consultas de películas con un actor específico.

Para alinear tu esquema con el comportamiento del usuario, haz lo siguiente:

1. Evaluar diversas búsquedas de diferentes usuarios
2. Identifica conjuntos de datos lógicos, o objetos, como una "película".
3. Identificar propiedades (atributos) como el título o la fecha de lanzamiento
4. Identificar valores válidos para las propiedades, como "Los cazadores del arca perdida".
5. Determinar las necesidades de ordenamiento y clasificación, como el orden cronológico o las calificaciones del público
6. Identificar propiedades de contexto, como el rol laboral, para mejorar las sugerencias de autocompletar
7. Haz una lista de estos objetos, propiedades y valores de ejemplo. Usa esta lista para definir opciones de operador.

Inicializa tu fuente de datos

Una fuente de datos representa los datos del repositorio indexados y almacenados en Google Cloud. Consulta Administra fuentes de datos de terceros. Cuando un usuario hace clic en un resultado, Cloud Search lo dirige al elemento con la URL de la solicitud de indexación.

Define tus objetos

El objeto es la unidad fundamental de un esquema. Las estructuras lógicas, como "película" o "persona", son objetos. Cada objeto tiene propiedades como título, duración o nombre.

Figura 1: Un esquema de ejemplo con dos objetos y un subobjeto.

Un esquema es una lista de definiciones de objetos en la etiqueta objectDefinitions.

{
  "objectDefinitions": [
    { "name": "movie" },
    { "name": "person" }
  ]
}

Usa nombres únicos para cada objeto, como movie. El servicio de esquema usa estos nombres como claves. Consulta ObjectDefinition.

Nota: Puedes ignorar el valor operationIds que se devuelve cuando solicitas un esquema registrado, ya que se refiere a operaciones pendientes.

Define las propiedades de los objetos

Define propiedades, como el título y la fecha de lanzamiento, en la sección propertyDefinitions. Usa options para freshnessOptions (clasificación) y displayOptions (etiquetas de la IU).

{
  "objectDefinitions": [{
    "name": "movie",
    "propertyDefinitions": [
      {
        "name": "movieTitle",
        "isReturnable": true,
        "textPropertyOptions": {
          "retrievalImportance": { "importance": "HIGHEST" },
          "operatorOptions": { "operatorName": "title" }
        },
        "displayOptions": { "displayLabel": "Title" }
      },
      {
        "name": "releaseDate",
        "isReturnable": true,
        "isSortable": true,
        "datePropertyOptions": {
          "operatorOptions": {
            "operatorName": "released",
            "lessThanOperatorName": "releasedbefore",
            "greaterThanOperatorName": "releasedafter"
          }
        }
      }
    ]
  }]
}

Nota: Los nombres de las propiedades dentro de un objeto deben ser únicos, independientemente del uso de mayúsculas.

Un objeto PropertyDefinition incluye lo siguiente:

• Es una cadena de name.
• Opciones independientes del tipo (p.ej., isReturnable).
• Un tipo y opciones específicas del tipo (p.ej., textPropertyOptions).
• operatorOptions para operadores de búsqueda
• displayOptions para las etiquetas de la IU.

Puedes reutilizar nombres de propiedades en diferentes objetos. Por ejemplo, movieTitle puede aparecer en la filmografía de un objeto movie y de un objeto person.

Nota: Cloud Search descarta los campos no registrados durante la indexación y rechaza las solicitudes con tipos de datos incorrectos.

Agrega opciones independientes del tipo

PropertyDefinition incluye opciones booleanas para configurar la funcionalidad de búsqueda de una propiedad, independientemente de su tipo. De forma predeterminada, estas opciones se establecen en false y deben establecerse en true para poder usarse.

• isReturnable: Se establece en true si los datos de la propiedad se deben mostrar en los resultados de la búsqueda con la API de Query. Las propiedades que no se pueden mostrar se pueden usar para buscar o clasificar sin aparecer en los resultados.
• isRepeatable: Se establece en true si la propiedad puede tener varios valores. Por ejemplo, una película tiene una fecha de estreno, pero varios actores.
• isSortable: Se establece en true si la propiedad se puede usar para ordenar. No puede ser true si isRepeatable es true o si la propiedad está dentro de un subobjeto repetible.
• isFacetable: Se establece en true si la propiedad se puede usar para generar facetas (atributos que se usan para definir mejor los resultados de la búsqueda).
  • Requiere que isReturnable sea true.
  • Solo se admite para las propiedades booleanas, de enumeración y de texto.
• isWildcardSearchable: Se establece en true para permitir que los usuarios realicen búsquedas con comodines en esta propiedad. Esta opción solo está disponible en las propiedades de texto y su comportamiento depende del parámetro de configuración exactMatchWithOperator:
  • Si exactMatchWithOperator es true: El valor de texto se trata como un solo token. Una búsqueda como science-* coincide con el valor science-fiction.
  • Si exactMatchWithOperator es false, el valor de texto se tokeniza. Una búsqueda como sci* o fi* coincide con science-fiction, pero science-* no.

Define el tipo

Para establecer el tipo de datos, define el objeto de opciones de propiedad adecuado (p.ej., textPropertyOptions). Usa enumeraciones (enumPropertyOptions) si conoces todos los valores posibles. Una propiedad solo puede tener un tipo de datos.

Define opciones de operador

operatorOptions describe cómo funciona una propiedad como operador de búsqueda.

Advertencia: Establece retrievalImportance en DEFAULT, a menos que tengas la certeza de que una propiedad requiere un rango más alto. No podrás modificar este parámetro de configuración más adelante.

Cada operatorOptions necesita un operatorName (p.ej., title). Este es el parámetro que los usuarios escriben en las búsquedas (p.ej., title:titanic). Usa nombres intuitivos y muéstralos a los usuarios.

Puedes compartir un operatorName entre propiedades del mismo tipo. Las búsquedas que usan ese nombre recuperan resultados de todas las propiedades coincidentes.

Las propiedades ordenables pueden incluir lessThanOperatorName y greaterThanOperatorName para las búsquedas de comparación. Las propiedades de texto pueden usar exactMatchWithOperator para tratar todo el valor como un solo token.

Cómo agregar opciones de visualización

La sección displayOptions opcional contiene un displayLabel. Esta es una etiqueta fácil de usar que se muestra en los resultados de la búsqueda.

Agrega operadores de filtrado de sugerencias

Usa suggestionFilteringOperators[] para definir una propiedad que filtre las sugerencias de autocompletar (p.ej., filtrar sugerencias de películas por el género preferido de un usuario). Solo puedes definir un filtro de sugerencias.

Registra el esquema

Registra tu esquema en el servicio de esquemas con el ID de tu fuente de datos. Genera una solicitud de UpdateSchema:

PUT https://cloudsearch.googleapis.com/v1/indexing/{name=datasources/*}/schema

Usa validateOnly: true para probar tu esquema sin registrarlo.

Indexa los datos

Después del registro, propaga la fuente de datos con llamadas al índice, por lo general, con un conector.

Ejemplo de solicitud de indexación:

{
  "name": "datasource/<data_source_id>/items/titanic",
  "metadata": {
    "title": "Titanic",
    "objectType": "movie"
  },
  "structuredData": {
    "object": {
      "properties": [{
        "name": "movieTitle",
        "textValues": { "values": ["Titanic"] }
      }]
    }
  },
  "itemType": "CONTENT_ITEM"
}

Nota: objectType debe coincidir con el nombre del objeto del esquema. Los nombres de las propiedades en la solicitud deben coincidir con el uso de mayúsculas y minúsculas del esquema.

Prueba el esquema.

Realiza pruebas con un repositorio pequeño antes de la producción. Crea un LCA que limite los resultados a un usuario de prueba.

• Consulta genérica: Busca una cadena (p.ej., "titanic") para ver todos los elementos coincidentes.
• Búsqueda con operador: Usa un operador (p.ej., actor:Zane) para limitar los resultados.

Ajusta el esquema

Supervisa los comentarios de los usuarios y ajusta tu esquema. Puedes indexar campos nuevos o cambiar el nombre de los operadores para que sean más intuitivos.

Vuelve a indexar después de un cambio de esquema

No es necesario que vuelvas a indexar para los cambios en los siguientes elementos:

• Nombres de operadores
• Límites numéricos.
• Es la clasificación ordenada.
• Opciones de actualización o visualización

Debes volver a indexar en los siguientes casos:

• Agregar o quitar propiedades u objetos
• Cambiar isReturnable, isFacetable o isSortable a true
• Marcar una propiedad como isSuggestable

Cambios de propiedad no permitidos

No se permiten los cambios que dañen el índice o provoquen resultados incoherentes, incluidos los siguientes:

• Es el tipo de datos o el nombre de la propiedad.
• Configuración de exactMatchWithOperator o retrievalImportance

Realiza un cambio de esquema complejo

Para realizar un cambio no permitido, migra las propiedades de una definición antigua a una nueva:

1. Agrega una propiedad nueva con un nombre diferente al esquema.
2. Registra el esquema con las propiedades nuevas y las anteriores.
3. Completa el índice solo con la propiedad nueva.
4. Borra la propiedad anterior del esquema.
5. Actualiza el código de tu consulta para usar el nuevo nombre de la propiedad.

Cloud Search registra los elementos borrados durante 30 días para evitar problemas de reutilización.

Limitaciones de tamaño

• Se pueden incluir hasta 10 objetos de nivel superior.
• Profundidad máxima de 10 niveles
• Un máximo de 1,000 campos por objeto (incluidos los campos anidados)

Próximos pasos

1. Crea una interfaz de búsqueda.
2. Mejorar la calidad de la búsqueda
3. Diseña la estructura de un esquema para optimizar la interpretación de consultas.
4. Define sinónimos.