Criar um índice básico no Azure SearchCreate a basic index in Azure Search

No Azure Search, um índice é o repositório persistente de documentos e outras construções usados para pesquisa filtrada e de texto completo em um serviço do Azure Search.In Azure Search, an index is a persistent store of documents and other constructs used for filtered and full text search on an Azure Search service. Conceitualmente, um documento é uma única unidade de dados pesquisáveis no índice.Conceptually, a document is a single unit of searchable data in your index. Por exemplo, uma loja de comércio eletrônico pode ter um documento para cada item vendido, uma agência de notícias pode ter um documento para cada artigo e assim por diante.For example, an e-commerce retailer might have a document for each item they sell, a news organization might have a document for each article, and so forth. Mapeando esses conceitos para equivalentes de banco de dados mais conhecidos: um índice é conceitualmente semelhante a uma tabela e documentos são equivalentes a linhas em uma tabela.Mapping these concepts to more familiar database equivalents: an index is conceptually similar to a table, and documents are roughly equivalent to rows in a table.

Ao adicionar ou carregar um índice, o Azure Search criará estruturas físicas com base no esquema que você fornecer.When you add or upload an index, Azure Search creates physical structures based on the schema you provide. Por exemplo, se um campo no índice estiver marcado como pesquisável, um índice invertido será criado para esse campo.For example, if a field in your index is marked as searchable, an inverted index is created for that field. Posteriormente, ao adicionar ou carregar documentos ou enviar consultas de pesquisa para o Azure Search, você estará enviando solicitações para um índice específico no serviço de pesquisa.Later, when you add or upload documents, or submit search queries to Azure Search, you are sending requests to a specific index in your search service. Carregar campos com valores de documento é chamado de indexação ou ingestão de dados.Loading fields with document values is called indexing or data ingestion.

É possível criar um índice no portal, na API REST ou no SDK do .NET.You can create an index in the portal, REST API, or .NET SDK.

Normalmente, chegar no design de índice correto é obtido por meio de várias iterações.Arriving at the right index design is typically achieved through multiple iterations. O uso de uma combinação de ferramentas e APIs pode ajudar você a finalizar seu design rapidamente.Using a combination of tools and APIs can help you finalize your design quickly.

  1. Determine se você pode usar um indexador.Determine whether you can use an indexer. Se os dados externos forem uma das fontes de dados com suporte, será possível criar um protótipo e carregar um índice usando o assistente Importar dados.If your external data is one of the supported data sources, you can prototype and load an index using the Import data wizard.

  2. Se você não puder usar Importar dados, ainda será possível criar um índice inicial no portal, adicionando campos, tipos de dados e atribuindo atributos usando controles na página Adicionar índice.If you can't use Import data, you can still create an initial index in the portal, adding fields, data types, and assigning attributes using controls on the Add Index page. O portal mostra quais atributos estão disponíveis para diferentes tipos de dados.The portal shows you which attributes are available for different data types. Se você for novo no design de índice, isso será útil.If you're new to index design, this is helpful.

    Adicionar página de índice mostrando atributos por tipo de dadosAdd index page showing attributes by data type

    Quando você clica em Criar, todas as estruturas físicas que dão suporte ao seu índice são criadas em seu serviço de pesquisa.When you click Create, all of the physical structures supporting your index are created in your search service.

  3. Baixe o esquema de índice usando a API REST Obter índice e uma ferramenta de teste da Web como Postman.Download the index schema using Get Index REST API and a web testing tool like Postman. Agora você tem uma representação JSON do índice criado no portal.You now have a JSON representation of the index you created in the portal.

    Você está mudando para uma abordagem baseada em código neste momento.You are switching to a code-based approach at this point. O portal não é adequado para iteração, porque não é possível editar um índice já criado.The portal is not well-suited for iteration because you cannot edit an index that is already created. Mas é possível usar o Postman e REST para as tarefas restantes.But you can use Postman and REST for the remaining tasks.

  4. Carregue seu índice com os dados.Load your index with data. O Azure Search aceita documentos JSON.Azure Search accepts JSON documents. Para carregar seus dados de maneira programática, é possível usar o Postman com documentos JSON no conteúdo da solicitação.To load your data programmatically, you can use Postman with JSON documents in the request payload. Se os dados não estiverem expressados facilmente como JSON, essa etapa será a mais trabalhosa.If your data is not easily expressed as JSON, this step will be the most labor intensive.

  5. Consulte seu índice, examine resultados e itere o esquema de índice até que você comece a ver os resultados esperados.Query your index, examine results, and further iterate on the index schema until you begin to see the results you expect. É possível usar o Gerenciador de pesquisa ou o Postman para consultar seu índice.You can use Search explorer or Postman to query your index.

  6. Continue usando o código para iterar em seu design.Continue using code to iterate over your design.

Como estruturas físicas são criadas no serviço do descartar e recriar índices é necessário sempre que você fizer alterações de material para uma definição de campo existente.Because physical structures are created in the service, dropping and recreating indexes is necessary whenever you make material changes to an existing field definition. Isso significa que, durante o desenvolvimento, você deve planejar recompilações frequentes.This means that during development, you should plan on frequent rebuilds. Considere trabalhar com um subconjunto de seus dados para acelerar as recompilações.You might consider working with a subset of your data to make rebuilds go faster.

O código, em vez de uma abordagem de portal, é recomendado para design iterativo.Code, rather than a portal approach, is recommended for iterative design. Se você depender do portal para a definição de índice, terá que preencher a definição de índice em cada recompilação.If you rely on the portal for index definition, you will have to fill out the index definition on each rebuild. Como alternativa, ferramentas como o Postman e a API REST são úteis para testes de prova de conceito quando os projetos de desenvolvimento ainda estão em fases iniciais.As an alternative, tools like Postman and the REST API are helpful for proof-of-concept testing when development projects are still in early phases. É possível fazer alterações incrementais em uma definição de índice em um corpo da solicitação e, em seguida, enviar a solicitação para seu serviço a fim de recriar um índice usando um esquema atualizado.You can make incremental changes to an index definition in a request body, and then send the request to your service to recreate an index using an updated schema.

Componentes de um índiceComponents of an index

Esquematicamente, um índice do Azure Search é composto dos seguintes elementos.Schematically, an Azure Search index is composed of the following elements.

A coleção de campos normalmente é a maior parte de um índice, onde cada campo é nomeado, digitado e atribuído com comportamentos permitidos que determinam como é usado.The fields collection is typically the largest part of an index, where each field is named, typed, and attributed with allowable behaviors that determine how it is used. Outros elementos incluem sugestores, perfis de pontuação, analisadores com partes de componentes para dar suporte à personalização, CORS e chave de criptografia opções.Other elements include suggesters, scoring profiles, analyzers with component parts to support customization, CORS and encryption key options.

{
  "name": (optional on PUT; required on POST) "name_of_index",
  "fields": [
    {
      "name": "name_of_field",
      "type": "Edm.String | Collection(Edm.String) | Edm.Int32 | Edm.Int64 | Edm.Double | Edm.Boolean | Edm.DateTimeOffset | Edm.GeographyPoint",
      "searchable": true (default where applicable) | false (only Edm.String and Collection(Edm.String) fields can be searchable),
      "filterable": true (default) | false,
      "sortable": true (default where applicable) | false (Collection(Edm.String) fields cannot be sortable),
      "facetable": true (default where applicable) | false (Edm.GeographyPoint fields cannot be facetable),
      "key": true | false (default, only Edm.String fields can be keys),
      "retrievable": true (default) | false,
      "analyzer": "name_of_analyzer_for_search_and_indexing", (only if 'searchAnalyzer' and 'indexAnalyzer' are not set)
      "searchAnalyzer": "name_of_search_analyzer", (only if 'indexAnalyzer' is set and 'analyzer' is not set)
      "indexAnalyzer": "name_of_indexing_analyzer", (only if 'searchAnalyzer' is set and 'analyzer' is not set)
      "synonymMaps": [ "name_of_synonym_map" ] (optional, only one synonym map per field is currently supported)
    }
  ],
  "suggesters": [
    {
      "name": "name of suggester",
      "searchMode": "analyzingInfixMatching",
      "sourceFields": ["field1", "field2", ...]
    }
  ],
  "scoringProfiles": [
    {
      "name": "name of scoring profile",
      "text": (optional, only applies to searchable fields) {
        "weights": {
          "searchable_field_name": relative_weight_value (positive #'s),
          ...
        }
      },
      "functions": (optional) [
        {
          "type": "magnitude | freshness | distance | tag",
          "boost": # (positive number used as multiplier for raw score != 1),
          "fieldName": "...",
          "interpolation": "constant | linear (default) | quadratic | logarithmic",
          "magnitude": {
            "boostingRangeStart": #,
            "boostingRangeEnd": #,
            "constantBoostBeyondRange": true | false (default)
          },
          "freshness": {
            "boostingDuration": "..." (value representing timespan leading to now over which boosting occurs)
          },
          "distance": {
            "referencePointParameter": "...", (parameter to be passed in queries to use as reference location)
            "boostingDistance": # (the distance in kilometers from the reference location where the boosting range ends)
          },
          "tag": {
            "tagsParameter": "..." (parameter to be passed in queries to specify a list of tags to compare against target fields)
          }
        }
      ],
      "functionAggregation": (optional, applies only when functions are specified) 
        "sum (default) | average | minimum | maximum | firstMatching"
    }
  ],
  "analyzers":(optional)[ ... ],
  "charFilters":(optional)[ ... ],
  "tokenizers":(optional)[ ... ],
  "tokenFilters":(optional)[ ... ],
  "defaultScoringProfile": (optional) "...",
  "corsOptions": (optional) {
    "allowedOrigins": ["*"] | ["origin_1", "origin_2", ...],
    "maxAgeInSeconds": (optional) max_age_in_seconds (non-negative integer)
  },
  "encryptionKey":(optional){
    "keyVaultUri": "azure_key_vault_uri",
    "keyVaultKeyName": "name_of_azure_key_vault_key",
    "keyVaultKeyVersion": "version_of_azure_key_vault_key",
    "accessCredentials":(optional){
      "applicationId": "azure_active_directory_application_id",
      "applicationSecret": "azure_active_directory_application_authentication_key"
    }
  }
}

Coleção e atributo de camposFields collection and field attributes

Quando você define o esquema, deve especificar o nome, tipo e atributos de cada campo no índice.As you define your schema, you must specify the name, type, and attributes of each field in your index. O tipo de campo classifica os dados armazenados nesse campo.The field type classifies the data that is stored in that field. Os atributos são definidos em campos individuais para especificar como o campo será usado.Attributes are set on individual fields to specify how the field is used. A tabela a seguir enumera os tipos e atributos que você pode especificar.The following tables enumerate the types and attributes you can specify.

Tipos de dadosData types

TypeType DESCRIÇÃODescription
Edm.StringEdm.String O texto que opcionalmente pode ser indexado para a pesquisa de texto completo (separação de palavras, derivação e assim por diante).Text that can optionally be tokenized for full-text search (word-breaking, stemming, and so forth).
Collection(Edm.String)Collection(Edm.String) Uma lista de cadeias de caracteres que opcionalmente podem ser indexadas para a pesquisa de texto completo.A list of strings that can optionally be tokenized for full-text search. Não há nenhum limite teórico superior no número de itens em uma coleção, mas o limite superior de 16 MB no tamanho da carga se aplica às coleções.There is no theoretical upper limit on the number of items in a collection, but the 16 MB upper limit on payload size applies to collections.
Edm.BooleanEdm.Boolean Contém valores true/false.Contains true/false values.
Edm.Int32Edm.Int32 Valores inteiros de 32 bits.32-bit integer values.
Edm.Int64Edm.Int64 Valores inteiros de 64 bits.64-bit integer values.
Edm.DoubleEdm.Double Dados numéricos de dupla precisão.Double-precision numeric data.
Edm.DateTimeOffsetEdm.DateTimeOffset Valores de data e hora representados no formato OData V4 (por exemplo, yyyy-MM-ddTHH:mm:ss.fffZ ou yyyy-MM-ddTHH:mm:ss.fff[+/-]HH:mm).Date time values represented in the OData V4 format (for example, yyyy-MM-ddTHH:mm:ss.fffZ or yyyy-MM-ddTHH:mm:ss.fff[+/-]HH:mm).
Edm.GeographyPointEdm.GeographyPoint Um ponto que representa uma localização geográfica em todo o mundo.A point representing a geographic location on the globe.

Você pode encontrar informações mais detalhadas sobre os tipos de dados com suporte do Azure Search.You can find more detailed information about Azure Search's supported data types here.

Atributos de índiceIndex attributes

Exatamente um campo no índice deve ser designado como um chave campo que identifica exclusivamente cada documento.Exactly one field in your index must be the designated as a key field that uniquely identifies each document.

Outros atributos determinam como um campo é usado em um aplicativo.Other attributes determine how a field is used in an application. Por exemplo, o pesquisável atributo é atribuído a todos os campos que devem ser incluídos em uma pesquisa de texto completo.For example, the searchable attribute is assigned to every field that should be included in a full text search.

As APIs usadas para criar um índice tem comportamentos diferentes do padrão.The APIs you use to build an index have varying default behaviors. Para o APIs REST, a maioria dos atributos estão habilitados por padrão (por exemplo, pesquisáveis e recuperáveis são verdadeiros para campos de cadeia de caracteres) e você geralmente só precisará defini-las se convém desativá-los.For the REST APIs, most attributes are enabled by default (for example, searchable and retrievable are true for string fields) and you often only need to set them if you want to turn them off. Para o SDK do .NET, o oposto é verdadeiro.For the .NET SDK, the opposite is true. Em qualquer propriedade que você não definir explicitamente, o padrão é desabilitar o comportamento de pesquisa correspondente, a menos que você o habilite especificamente.On any property you do not explicitly set, the default is to disable the corresponding search behavior unless you specifically enable it.

AtributoAttribute DESCRIÇÃODescription
key Uma cadeia de caracteres que fornece a ID exclusiva de cada documento, usada para pesquisar documentos.A string that provides the unique ID of each document, used for document lookup. Todos os índices devem ter uma chave.Every index must have one key. Somente um campo pode ser a chave e seu tipo deve ser definido para Edm.String.Only one field can be the key, and its type must be set to Edm.String.
retrievable Especifica se um campo pode ser retornado em um resultado da pesquisa.Specifies whether a field can be returned in a search result.
filterable Permite que o campo seja usado nas consultas de filtro.Allows the field to be used in filter queries.
Sortable Permite que uma consulta classifique os resultados da pesquisa usando esse campo.Allows a query to sort search results using this field.
facetable Permite que um campo seja usado em uma estrutura de navegação mista para a filtragem autodirecionada do usuário.Allows a field to be used in a faceted navigation structure for user self-directed filtering. Normalmente, os campos que contêm valores repetidos que você pode usar para agrupar vários documentos (por exemplo, vários documentos que estejam em uma única categoria de marca ou de serviço) funcionam melhor como facetas.Typically fields containing repetitive values that you can use to group multiple documents together (for example, multiple documents that fall under a single brand or service category) work best as facets.
searchable Marca o campo como texto completo pesquisável.Marks the field as full-text searchable.

Implicações de armazenamentoStorage implications

Os atributos selecionados têm um impacto no armazenamento.The attributes you select have an impact on storage. A captura de tela a seguir ilustra padrões de armazenamento de índice resultantes de várias combinações de atributos.The following screenshot illustrates index storage patterns resulting from various combinations of attributes.

O índice se baseia a exemplo interno de imóveis fonte de dados, você pode indexar e consultar no portal.The index is based on the built-in real estate sample data source, which you can index and query in the portal. Embora os esquemas de índice não sejam mostrados, é possível inferir os atributos com base no nome do índice.Although the index schemas are not shown, you can infer the attributes based on the index name. Por exemplo, o índice realestate-searchable tem o atributo searchable selecionado e nada mais, o índice realestate-retrievable tem o atributo retrievable selecionado e nada mais e assim por diante.For example, realestate-searchable index has the searchable attribute selected and nothing else, realestate-retrievable index has the retrievable attribute selected and nothing else, and so forth.

Indexar tamanho com base na seleção de atributoIndex size based on attribute selection

Embora essas variantes de índice sejam artificiais, podemos referenciá-las para obter amplas comparações de como os atributos afetam o armazenamento.Although these index variants are artificial, we can refer to them for broad comparisons of how attributes affect storage. A configuração recuperável aumenta o tamanho do índice?Does setting retrievable increase index size? Não.No. A adição de campos a um Sugestor aumenta o tamanho do índice?Does adding fields to a Suggester increase index size? Sim.Yes.

Os índices que dão suporte à filtragem e à classificação são proporcionalmente maiores do que os índices que dão suporte apenas à pesquisa de texto completo.Indexes that support filter and sort are proportionally larger than indexes that support just full text search. O motivo é que isso filtra e classifica consultas em correspondências exatas, assim os documentos são armazenados intactos.The reason is that filter and sort query on exact matches so documents are stored intact. Por outro lado, os campos pesquisáveis que dão suporte à pesquisa de texto completo e difusa usam índices invertidos, populados com termos indexados que consomem menos espaço do que documentos inteiros.In contrast, searchable fields supporting full-text and fuzzy search use inverted indexes, which are populated with tokenized terms that consume less space than whole documents.

Observação

A arquitetura de armazenamento é considerada um detalhe de implementação do Azure Search e poderia alterada sem aviso prévio.Storage architecture is considered an implementation detail of Azure Search and could change without notice. Não há nenhuma garantia de que o comportamento atual persistirá no futuro.There is no guarantee that current behavior will persist in the future.

SugestoresSuggesters

Um sugestor é uma seção do esquema que define quais campos em um índice são usados para dar suporte a consultas de preenchimento automático ou digitação antecipada em pesquisas.A suggester is a section of the schema that defines which fields in an index are used to support auto-complete or type-ahead queries in searches. Normalmente, cadeias de caracteres de pesquisa parciais são enviadas às Sugestões (API REST) enquanto o usuário está digitando uma consulta de pesquisa e a API retorna um conjunto de frases sugeridas.Typically, partial search strings are sent to the Suggestions (REST API) while the user is typing a search query, and the API returns a set of suggested phrases.

Os campos adicionados a um sugestor são usados para criar termos de pesquisa de digitação antecipada.Fields added to a suggester are used to build type-ahead search terms. Todos os termos de pesquisa são criados durante a indexação e armazenados separadamente.All of the search terms are created during indexing and stored separately. Para saber mais sobre como criar uma estrutura de sugestor, confira Add suggesters (Adicionar sugestores).For more information about creating a suggester structure, see Add suggesters.

Perfis de pontuaçãoScoring profiles

Um perfil de pontuação é uma seção do esquema que define comportamentos de pontuação personalizados que permitem influenciar quais itens são exibidos em uma posição mais alta nos resultados da pesquisa.A scoring profile is a section of the schema that defines custom scoring behaviors that let you influence which items appear higher in the search results. Perfis de pontuação são compostos de funções e pesos de campos.Scoring profiles are made up of field weights and functions. Para usá-las, você pode especificar um perfil por nome na sequência de consulta.To use them, you specify a profile by name on the query string.

Um padrão de pontuação perfil funciona nos bastidores para calcular uma pontuação para cada item em um conjunto de resultados de pesquisa.A default scoring profile operates behind the scenes to compute a search score for every item in a result set. Você pode usar o perfil de pontuação interno e sem o nome.You can use the internal, unnamed scoring profile. Como alternativa, defina defaultScoringProfile para usar um perfil personalizado como o padrão, invocado sempre que um perfil personalizado não é especificado na cadeia de caracteres de consulta.Alternatively, set defaultScoringProfile to use a custom profile as the default, invoked whenever a custom profile is not specified on the query string.

AnalisadoresAnalyzers

O elemento analisadores define o nome do analisador de linguagem a ser usado para o campo.The analyzers element sets the name of the language analyzer to use for the field. Para saber mais sobre o intervalo de analisadores disponíveis para você, confira Adding analyzers to an Azure Search index (Adicionando analisadores ao índice do Azure Search).For more information about the range of analyzers available to you, see Adding analyzers to an Azure Search index. Os analisadores só podem ser usados com campos pesquisáveis.Analyzers can only be used with searchable fields. Depois que o analisador é atribuído a um campo, ele não pode ser alterado, a menos que você recompile o índice.Once the analyzer is assigned to a field, it cannot be changed unless you rebuild the index.

CORSCORS

O JavaScript do lado do cliente não pode chamar nenhuma API por padrão, pois o navegador impedirá todas as solicitações entre origens.Client-side JavaScript cannot call any APIs by default since the browser will prevent all cross-origin requests. Para permitir ao índice as consultas entre origens, habilite o CORS (Compartilhamento de Recursos entre Origens) definindo o atributo corsOptions.To allow cross-origin queries to your index, enable CORS (Cross-Origin Resource Sharing) by setting the corsOptions attribute. Por motivos de segurança, apenas APIs de consulta dão suporte para CORS.For security reasons, only query APIs support CORS.

As seguintes opções podem ser definidas para CORS:The following options can be set for CORS:

  • allowedOrigins (obrigatório): Essa é uma lista de origens que receberão acesso ao índice.allowedOrigins (required): This is a list of origins that will be granted access to your index. Isso significa que qualquer código JavaScript atendendo a partir dessas origens terá permissão para consultar o índice (supondo que ele forneça a chave de API correta).This means that any JavaScript code served from those origins will be allowed to query your index (assuming it provides the correct api-key). Cada origem é tipicamente da forma, protocol://<fully-qualified-domain-name>:<port> embora <port> seja frequentemente omitida.Each origin is typically of the form protocol://<fully-qualified-domain-name>:<port> although <port> is often omitted. Consulte Compartilhamento de recursos entre origens (Wikipédia) para obter mais detalhes.See Cross-origin resource sharing (Wikipedia) for more details.

    Se você quiser permitir acesso a todas as origens, inclua * como um único item na matriz allowedOrigins.If you want to allow access to all origins, include * as a single item in the allowedOrigins array. Essa não é uma prática recomendada para serviços de pesquisa de produção, mas geralmente é útil para desenvolvimento e depuração.This is not recommended practice for production search services but it is often useful for development and debugging.

  • maxAgeInSeconds (opcional): Os navegadores usam esse valor para determinar a duração (em segundos) para armazenar em cache as respostas CORS de simulação.maxAgeInSeconds (optional): Browsers use this value to determine the duration (in seconds) to cache CORS preflight responses. Esse deve ser um inteiro não negativo.This must be a non-negative integer. Quanto maior for esse valor, melhor será o desempenho, porém, mais tempo levará para que as alterações de política CORS entrem em vigor.The larger this value is, the better performance will be, but the longer it will take for CORS policy changes to take effect. Se ele não for definido, uma duração padrão de cinco minutos será usada.If it is not set, a default duration of 5 minutes will be used.

Chave de criptografiaEncryption Key

Enquanto todos os índices de pesquisa do Azure são criptografados por padrão usando chaves gerenciadas pela Microsoft, os índices podem ser configurados para serem criptografados com chaves gerenciadas do cliente no cofre de chaves.While all Azure search indexes are encrypted by default using Microsoft managed keys, indexes can be configured to be encrypted with customer managed keys in Key Vault. Para obter mais informações, consulte gerenciar chaves de criptografia no Azure Search.To learn more, see Manage encryption keys in Azure Search.

Próximas etapasNext steps

Com o conhecimento adquirido sobre a composição de índice, você poderá continuar no portal para criar seu primeiro índice.With an understanding of index composition, you can continue in the portal to create your first index.