IBM Cloud Docs
Usando o IBM Cloudant Query

Usando o IBM Cloudant Query

Neste tutorial, demonstramos como criar um índice e usá-lo para consultar o banco de dados. Você também aprenderá a criar diferentes tipos de consultas para localizar dados com mais facilidade.

Aqui você executa os comandos na linha de comandos, mas também é possível concluir essas tarefas com o painel do IBM® Cloudant® for IBM Cloud®, o que fornece a você um exemplo visual de cada tarefa. Para obter mais informações sobre o painel, consulte o tutorial Usando o painel do IBM Cloudant.

Antes de iniciar

Antes de começar, siga estes tutoriais para criar uma instância e, em seguida, crie e preencha um banco de dados.

  1. Crie uma instância do IBM Cloudant .
  2. Criar um banco de dados.
  3. Preencher o banco de dados.
  4. (Opcional) Crie um alias acurl.

Se você decidir não configurar o acurl, use a URL a seguir com curl no lugar da fornecida nos exercícios, curl "https://$USERNAME:$PASSWORD@$ACCOUNT.cloudant.com/databasedemo".

O alias acurl é mais seguro. Isso evita que alguém leia sua senha sem você perceber, conforme você digita. Também garante que sua senha não seja enviada em texto sem formatação pela rede, aplicando HTTPS.

Agora, estamos prontos para aprender como executar consultas no banco de dados que você criou na etapa dois de Antes de iniciar.

Criando um índice

O IBM Cloudant Query usa sintaxe de consulta em estilo Mongo para pesquisar documentos usando operadores lógicos. O IBM Cloudant Query é uma combinação de uma visualização e um índice de procura.

Ao usar o IBM Cloudant Query, o planejador de consulta examina o seletor (sua consulta) para determinar o índice correto a escolher. Na memória, você filtra os documentos pelo seletor, razão pela qual, mesmo sem um índice, ainda é possível consultar com vários campos.

Se nenhum índice definido disponível corresponde à consulta especificada, o IBM Cloudant usa o índice _all_docs, que consulta documentos por ID. No pior cenário de caso, ele retorna todos os documentos por ID (varredura de tabela integral). As varreduras de mesa completa são caras para processar. É recomendado que você crie um índice.

Para criar um índice, siga essas etapas:

  1. Copie os dados JSON de amostra a seguir em um arquivo denominado query-demo-index.json:

      {
  	"index": {
  		"fields": [
  			"descriptionField",
  			"temperatureField"
  		],
  		"partial_filter_selector": {
  			"descriptionField": {
  				"$eq": "hot"
  			},
  			"temperatureField": {
  				"$gt": 50
  			}
  		}
  	},
  	"ddoc": "query-demo-index",
  	"type": "json"
  }

  2. Execute o comando a seguir para criar um índice:

      acurl "https://$ACCOUNT.cloudant.com/databasedemo/_index" \
    -X POST \
    -H "Content-Type: application/json" \
    -d \@query-demo-index.json

  3. Revise os resultados:

      {
  	"result": "created",
  	"id": "_design/query-demo-index",
  	"name": "490441584f9eddb8d09ef234d636b5f3b18e4ce6"
  }

Você não é obrigado a criar um índice para executar uma consulta. No entanto, se você não fizer isso, o aviso a seguir será incluído em seus resultados como um indicador de que a criação de um índice reduz o processamento e torna suas consultas mais efetivas. "Warning": "No matching index found, create an index to optimize query time."

Executando uma consulta simples

Este exemplo demonstra como o IBM Cloudant Query localiza documentos com base no descriptionField com o valor boiling.

Para executar a consulta, execute estas etapas:

  1. Copie o JSON de amostra a seguir em um arquivo de dados denominado query1.json:
     {
  "selector": {
    "descriptionField": "boiling"
   }
 }
  2. Execute o comando a seguir para consultar o banco de dados:
      acurl "https://$ACCOUNT.cloudant.com/databasedemo/_find" \
    -X POST \
    -H "Content-Type: application/json" \
    -d \@query1.json
  3. Revise os resultados da consulta:
      {
  	"docs": [{
  		"_id": "91d1fa833d28efe15069604f98de701d",

  		"_rev": "1-f998fc7b89d4466c1e7bb204b1b00f74",
		"numberField": 1,
  		"nameField": "one",
  		"descriptionField": "boiling",
  		"temperatureField": 100
   	}],
  	"bookmark":  "g1AAAABweJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYorWBqmGKYlWhgbpxhZpKalGpoamFmaGZikWVqkpJobGKaA9HHA9BGlIwsAmn8eLw",
  	"warning": "No matching index found, create an index to optimize query time."
   }

Em seguida, você localizará um documento no banco de dados usando dois campos.

Executando uma consulta com dois campos

Este exemplo usa dois campos para localizar um documento com os valores: freezing e -5.

A procura é descrita usando uma expressão 'selector' que é semelhante ao exemplo a seguir:

  {
  	"selector": {
  		"descriptionField": "freezing",
  		"temperatureField": -5
  	}
  }

É possível adequar os resultados, incluindo mais detalhes na expressão selector. O parâmetro fields especifica os campos a serem incluídos com os resultados. Em nosso exemplo, os resultados incluem o nameField, o descriptionField e o temperatureField, conforme mostrado no exemplo a seguir.

  {
  	...
  	"fields": [
  		"nameField",
  		"descriptionField",
  		"temperatureField"
  	]
  }

Para executar a consulta, execute estas etapas:

  1. Copie o JSON de amostra em um arquivo de dados denominado query2.json.
      {
  	"selector": {
  		"descriptionField": "freezing",
  		"temperatureField": -5
  	},
  	"fields": [
  		"nameField",
  		"descriptionField",
  		"temperatureField"
  	]
  }
  2. Execute o comando a seguir para consultar o banco de dados:
      acurl "https://$ACCOUNT.cloudant.com/databasedemo/_find" \
    -X POST \
    -H "Content-Type: application/json" \
    -d \@query2.json
  3. Revise os resultados da consulta:
    {
	"docs": [{
		"nameField": "eight",
		"descriptionField": "freezing",
		"temperatureField": -5
	}],
	"bookmark": "g1AAAABweJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYorpBiYGJolWaSZmaWYpFqmGBiYmKclphhappqZmRglG5uD9HHA9BGlIwsAms8eJw",
	"warning": "No matching index found, create an index to optimize query time."
}

Em seguida, você localizará um documento no banco de dados usando diversos operadores.

Executando uma consulta com operadores

Neste exemplo, os operadores $gt (maior que) e $eq (igual) são usados para procurar documentos que incluam uma temperatura maior que 20 graus e uma descrição que contém o valor hot. Os resultados incluem o descriptionField e o temperatureField, mostrados em ordem decrescente por temperatura.

Você usa uma expressão selector como no exemplo a seguir:

  {
  	"selector": {
  		"temperatureField": {
  			"$gt": 50
  		},
  		"descriptionField": {
  			"$eq": "hot"
  		}
  	},
  	"fields": [
  		"descriptionField",
  		"temperatureField"
  	],
  	"sort": [{
  		"temperatureField": "desc"
  	}],
  	"use_index": "_design/query-demo-index"
  }

Para executar a consulta, execute estas etapas:

  1. Copie o JSON de amostra a seguir em um arquivo denominado query3.json.
      {
  	"selector": {
  		"descriptionField": {
  			"$eq": "hot"
  		},
  		"temperatureField": {
  			"$gt": 50
  		}
  	},
  	"fields": [
  		"descriptionField",
  		"temperatureField"
  	],
  	"sort": [{
  		"temperatureField": "desc"
  	}],
  	"use_index": "_design/query-demo-index"
  }
  2. Execute esta consulta:
      acurl "https://$ACCOUNT.cloudant.com/databasedemo/_find" \
    -X POST \
    -H "Content-Type: application/json" \
    -d \@query3.json
  3. Revise os resultados da consulta:
    {
	"docs": [{
			"descriptionField": "hot",
			"temperatureField": 97
		},
		{
			"descriptionField": "hot",
			"temperatureField": 75
		}
	],
	"bookmark": "g1AAAABbeJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYorJBoYmKWaWVokpZkamJtaGJskm5slmSenGhulWpibJhqC9HHA9OWATErUAGlkzsgvycoCAEsUF_A"
}

Agora você saber como extrair dados do seu banco de dados usando IBM Cloudant Query. Para obter mais informações, consulte a documentação do IBM Cloudant.