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 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 incluyen los conceptos básicos de la creación de esquemas. Para optimizar la experiencia de búsqueda, consulta Mejora la calidad de 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 el esquema.
6. Indexa los datos.
7. Prueba el esquema.
8. Ajusta el 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 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. Evalúa diversas consultas de diferentes usuarios.
2. Identifica conjuntos de datos lógicos o objetos, como una "película".
3. Identifica propiedades (atributos) como el título o la fecha de lanzamiento.
4. Identifica valores válidos para las propiedades, como "En busca del arca perdida".
5. Determina las necesidades de ordenamiento y clasificación, como el orden cronológico o las calificaciones del público.
6. Identifica las 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 las opciones de operador.

Inicializa tu fuente de datos

Una fuente de datos representa los datos indexados del repositorio 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 que muestra 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 los operationIds que se muestran cuando solicitas un esquema registrado. Se refieren a las 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 de las mayúsculas.

PropertyDefinition incluye lo siguiente:

• Una cadena 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 etiquetas de la IU

Puedes reutilizar los nombres de las propiedades en diferentes objetos. Por ejemplo, movieTitle puede aparecer en un objeto movie y en la filmografía 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 configurarse como true para usarse.

• isReturnable: Se establece en true si los datos de la propiedad deben mostrarse en los resultados de la búsqueda con la API de consulta. Las propiedades que no se pueden mostrar se pueden usar para buscar o clasificar sin que aparezcan en los resultados.
• isRepeatable: Se establece en true si la propiedad puede tener varios valores. Por ejemplo, una película tiene una fecha de lanzamiento, pero varios actores.
• isSortable: Se establece en true si la propiedad se puede usar para el ordenamiento. 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 refinar 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 de la configuración de exactMatchWithOperator:
  • Si exactMatchWithOperator es true, el valor de texto se trata como un solo token. Una consulta como science-* coincide con el valor science-fiction.
  • Si exactMatchWithOperator es false, el valor de texto se tokeniza. Una consulta 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 enums (enumPropertyOptions) si conoces todos los valores posibles. Una propiedad puede tener solo un tipo de datos.

Define opciones de operador

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

Advertencia: Establece retrievalImportance en DEFAULT, a menos que estés seguro de que una propiedad requiere una clasificación más alta. No puedes cambiar esta configuración más adelante.

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

Puedes compartir un operatorName en las propiedades del mismo tipo. Las consultas que usan ese nombre recuperan resultados de todas las propiedades coincidentes.

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

Agrega opciones de visualización

La sección opcional displayOptions contiene una 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 según el género preferido de un usuario). Solo puedes definir un filtro de sugerencias.

Registra el esquema

Registra tu esquema con el servicio de esquema usando el ID de tu fuente de datos. Genera una 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 de esquema. Los nombres de las propiedades de la solicitud deben coincidir con el uso de mayúsculas del esquema.

Prueba el esquema.

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

• Búsqueda genérica: Busca una cadena (p.ej., "titanic") para ver todos los elementos coincidentes.
• Consulta de 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 lo siguiente:

• Nombres de operadores
• Límites numéricos
• Clasificación ordenada
• Opciones de actualización o visualización

Debes volver a indexar para lo siguiente:

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

Cambios de propiedad no permitidos

No se permiten los cambios que interrumpen el índice o causan resultados incoherentes, incluidos los siguientes:

• Tipo de datos o 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 anterior a una nueva:

1. Agrega una propiedad nueva con un nombre diferente al esquema.
2. Registra el esquema con las propiedades nuevas y anteriores.
3. Rellena el índice usando solo la propiedad nueva.
4. Borra la propiedad anterior del esquema.
5. Actualiza el código de la 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

• Un máximo de 10 objetos de nivel superior
• Una 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. Mejora la calidad de búsqueda.
3. Diseña la estructura de un esquema para optimizar la interpretación de consultas.
4. Define sinónimos.