Trabalhando com o IBM Cloudant Query
IBM® Cloudant® for IBM Cloud® Query é uma sintaxe declarativa de consulta JSON para bancos de dados IBM Cloudant. É possível usar um tipo de índice json ou text com IBM Cloudant.
Nos casos a seguir, é possível especificar como o índice é criado, tornando-o do tipo json:
- Você sabe exatamente quais dados deseja procurar.
- Você deseja manter os requisitos de armazenamento e processamento em um mínimo.
Mas, para obter flexibilidade máxima ao procurar dados, geralmente você cria um índice do tipo text. Os índices do tipo text têm um mecanismo simples para indexar automaticamente todos os campos nos documentos.
Embora mais flexíveis, os índices text podem demorar mais para serem criados e requerem mais recursos de armazenamento do que os índices json.
Criando um índice
É possível criar um índice com um dos tipos a seguir:
"type": "json""type": "text"
Criando um índice type=json
Para criar um índice JSON no banco de dados $DATABASE, faça uma solicitação POST para /$DATABASE/_index com um objeto JSON que descreve o índice no corpo da solicitação. O campo de type do
objeto JSON deve ser configurado como json. Um índice JSON pode ser particionado ou global; essa opção é configurada usando o campo partitioned.
Veja o exemplo a seguir que usa HTTP para solicitar um índice do tipo JSON:
POST /$DATABASE/_index HTTP/1.1
Content-Type: application/json
Veja o exemplo a seguir de um objeto JSON que cria um índice particionado que é chamado foo-partitioned-index para o campo chamado foo:
{
"index": {
"fields": ["foo"]
},
"name" : "foo-partitioned-index",
"type" : "json",
"partitioned": true
}
Veja o exemplo a seguir de um objeto JSON que cria um índice global chamado bar-global-index para o campo chamado bar:
{
"index": {
"fields": ["bar"]
},
"name" : "bar-global-index",
"type" : "json",
"partitioned": false
}
Veja o exemplo a seguir de JSON retornado, confirmando que o índice foi criado:
{
"result": "created"
}
| Campo | Descrição |
|---|---|
index |
campos - Uma matriz JSON de nomes de campo que usa a sintaxe de classificação. Os campos aninhados também são permitidos, por exemplo, person.name. |
ddoc (opcional) |
Nome do documento de design no qual o índice é criado. Por padrão, cada índice é criado em seu próprio documento de design. Os índices podem ser agrupados em documentos de design para uma maior eficiência. No entanto, uma mudança para um índice em um documento de design invalida todos os outros índices no mesmo documento. |
type (opcional) |
Pode ser json ou text. Padronizado para json. |
name (opcional) |
Nome do índice. Se nenhum nome for fornecido, um nome será gerado automaticamente. |
partitioned (opcional, booleano) |
Determina se esse índice é particionado. Para obter mais informações, consulte o campo partitioned. |
O campo partitioned
Esse campo configura se o índice criado é particionado ou global.
| Valor | Descrição | Notas |
|---|---|---|
true |
Crie o índice como particionado. | Pode ser usado apenas em um banco de dados particionado. |
false |
Crie o índice como global. | Pode ser usado em qualquer banco de dados. |
O padrão segue a configuração partitioned para o banco de dados:
| O banco de dados está particionado? | Valor partitioned padrão |
Valores permitidos |
|---|---|---|
| True | true |
true, false |
| Não | false |
false |
É importante reiterar que o valor padrão partitioned é true para índices que são criados em um banco de dados particionado. Esse valor padrão significa que o índice não pode ser usado para satisfazer consultas
globais.
| Código | Descrição |
|---|---|
| 200 | O índice foi criado com sucesso ou existia no banco de dados. |
| 400 | Solicitação inválida - o corpo da solicitação não tem o formato especificado. |
Criando um índice type=text
Quando você cria um índice de texto único, uma boa prática é usar os valores padrão, mas alguns atributos de índice úteis podem ser modificados.
Um índice text pode ser particionado ou global; essa opção é configurada usando o campo partitioned.
Para os índices de texto completo (FTIs), o type deve ser configurado como text.
Os atributos name e ddoc são para agrupar índices em documentos de design. Use os atributos para referir-se a grupos de índice usando um valor de sequência customizado. Se nenhum valor for fornecido para esses campos,
eles serão preenchidos automaticamente com um valor de hash.
Se você criar vários índices de texto em um banco de dados, com o mesmo valor ddoc, será necessário saber pelo menos o valor ddoc e o valor name. A criação de diversos índices com o mesmo valor ddoc os coloca no mesmo documento de design. Geralmente, deve-se colocar cada índice de texto em seu próprio documento de design.
Para obter mais informações, consulte mais sobre text índices.
Veja o exemplo a seguir de um documento JSON que solicita uma criação de índice particionado:
{
"index": {
"fields": [
{
"name": "Movie_name",
"type": "string"
}
]
},
"name": "Movie_name-text",
"type": "text",
"partitioned": true
}
Veja o exemplo a seguir do documento JSON que solicita uma criação de índice global:
{
"index": {
"fields": [
{
"name": "Movie_name",
"type": "string"
}
]
},
"name": "Movie_name-text",
"type": "text",
"partitioned": false
}
Veja o exemplo a seguir de um documento JSON que solicita a criação de um índice particionado mais complexo:
{
"type": "text",
"name": "my-index",
"ddoc": "my-index-design-doc",
"index": {
"default_field": {
"enabled": true,
"analyzer": "german"
},
"selector": {},
"fields": [
{"name": "married", "type": "boolean"},
{"name": "lastname", "type": "string"},
{"name": "year-of-birth", "type": "number"}
]
},
"partitioned": true
}
O campo index
O campo index contém configurações específicas para índices de texto.
Para indexar todos os campos em todos os documentos automaticamente, use a sintaxe simples:
"index": {}
O processo de indexação atravessa todos os campos em todos os documentos no banco de dados.
No banco de dados de demonstração dos filmes de exemplo, você pode ver um exemplo de um índice de texto que contém todos os campos e todos os documentos em um banco de dados.
Tome cuidado ao indexar todos os campos em todos os documentos para conjuntos de dados grandes, pois essa atividade pode consumir muitos recursos.
Veja o exemplo a seguir de um documento JSON que solicita a criação de um índice de todos os campos em todos os documentos:
{
"type": "text",
"index": { }
}
O campo default_field
O valor default_field especifica como o operador $text pode ser usado com o índice.
O default_field inclui duas chaves:
| Chave | Descrição |
|---|---|
enabled |
Ative ou desative o default_field index. O valor padrão é true. |
A chave analyzer no default_field especifica como o índice analisa o texto. Mais tarde, o índice pode ser consultado usando o operador $text. Para obter mais informações, consulte a Documentação de procura para analisadores alternativos. É possível escolher um analisador alternativo quando os documentos são indexados em idiomas diferentes do inglês ou quando você tem outros requisitos especiais para o analisador, como correspondência de
endereços de e-mail.
Se o default_field não for especificado ou for fornecido com um objeto vazio, ele será padronizado como true e o analisador standard será usado.
A matriz fields
A matriz fields inclui uma lista de campos que devem ser indexados para cada documento. Esse campo poderá ser usado para limitar o tamanho do índice se você souber que ele consulta apenas campos específicos. Cada campo deve
também especificar um tipo a ser indexado. Os tipos aceitáveis são mostrados na lista a seguir:
"boolean""string""number"
O campo index_array_lengths
Os índices de texto do IBM Cloudant Query têm uma propriedade que é chamada index_array_lengths. Se a propriedade não estiver configurada explicitamente, o valor padrão será true.
Se o campo for configurado como true, o índice requererá trabalho adicional. Esse trabalho contém uma varredura de cada documento para quaisquer matrizes, além de criar um campo para manter o comprimento para cada matriz localizada.
É possível configurar o campo index_array_lengths como false nas situações a seguir:
- Não é preciso saber o comprimento de uma matriz.
- Você não usa o operador
$size. - Os documentos em seu banco de dados são complexos ou não estão completamente sob o seu controle. Como resultado, é difícil estimar o impacto do processamento adicional que é necessário para determinar e armazenar os tamanhos de matriz.
O operador $size requer que você defina o campo index_array_lengths como true. Caso contrário, o operador não pode funcionar.
Veja o documento JSON de exemplo a seguir com configurações sugeridas para otimizar o desempenho em sistemas de produção:
{
"default_field": {
"enabled": false
},
"index_array_lengths": false
}
O campo partitioned
Esse campo determina se o índice criado é um índice particionado ou global.
| Valor | Descrição | Notas |
|---|---|---|
true |
Crie o índice como particionado. | Pode ser usado apenas em um banco de dados particionado. |
false |
Crie o índice como global. | Pode ser usado em qualquer banco de dados. |
O padrão segue a configuração partitioned para o banco de dados:
| O banco de dados está particionado? | Valor partitioned padrão |
Valores permitidos |
|---|---|---|
| True | true |
true, false |
| Não | false |
false |