IBM Cloud Docs
IBM Cloudant Operadoras

IBM Cloudant Operadoras

Operadores são identificados pelo uso de um prefixo de símbolo de dólar ($) no campo de nome.

A sintaxe do seletor tem dois tipos principais de operadores:

  • Operadores de combinação
  • Operadores de condição

Em geral, os operadores de combinação são aplicados no nível mais alto de seleção. Eles são usados para combinar condições, ou para criar combinações de condições, em um seletor.

Cada operador explícito tem o formato:

{
	"$operator": "argument"
}

Um seletor sem um operador explícito é considerado como operador implícito. O operador implícito exato é determinado pela estrutura da expressão de seletor.

Operadores implícitos

Os dois operadores implícitos são mostrados na lista a seguir:

  • "Igualdade"
  • "E"

Em um seletor, qualquer campo que contenha um valor JSON, mas que não tenha operadores nele, é considerado como condição de igualdade. O teste de igualdade implícito também se aplica para campos e subcampos.

Qualquer objeto JSON que não seja o argumento para um operador de condição é um operador implícito $and em cada campo.

Veja o seletor de exemplo a seguir que usa um operador para corresponder a qualquer documento, em que o campo year tem um valor maior que 2010:

{
	"selector": {
		"year": {
			"$gt": 2010
		}
	}
}

No exemplo a seguir, um documento correspondente deve ter um campo que é chamado de director e o campo deve ter um valor exatamente igual a Lars von Trier.

Veja o exemplo a seguir do operador de igualdade implícito:

{
	"director": "Lars von Trier"
}

Também é possível tornar explícito o operador de igualdade, conforme mostrado no exemplo a seguir.

Consulte o exemplo a seguir de um operador de igualdade explícito:

{
	"director": {
		"$eq": "Lars von Trier"
	}
}

No exemplo a seguir que usa subcampos, o campo imdb em um documento correspondente também deve ter um subcampo rating e o subcampo deve ter um valor igual a 8.

Veja o exemplo a seguir de operador implícito que é aplicado a um teste de subcampo:

{
	"imdb": {
		"rating": 8
	}
}

É possível tornar explícito o operador da igualdade.

Consulte o exemplo a seguir de um operador de igualdade explícito:

{
	"selector": {
		"imdb": {
			"rating": { "$eq": 8 }
		}
	}
}

Veja o exemplo a seguir de um operador $eq que é usado com índice de texto total:

{
	"selector": {
		"year": {
			"$eq": 2001
		}
	},
	"sort": [
		"title:string"
	],
	"fields": [
		"title"
	]
}

Veja o exemplo a seguir de um operador $eq que é usado com um banco de dados que é indexado no campo year:

{
	"selector": {
		"year": {
			"$eq": 2001
		}
	},
	"sort": [
		"year"
	],
	"fields": [
		"year"
	]
}

No exemplo a seguir, o campo director deve estar presente e conter o valor Lars von Trier e o campo year deve existir e ter o valor 2003.

Veja o exemplo a seguir de um operador $and implícito:

{
	"director": "Lars von Trier",
	"year": 2003
}

É possível tornar explícito tanto o operador $and quanto o operador de igualdade.

Veja o exemplo a seguir que usa operadores explícitos $and e $eq:

{
	"$and": [
		{
			"director": {
				"$eq": "Lars von Trier"
			}
		},
		{
			"year": {
				"$eq": 2003
			}
		}
	]
}

Operadores explícitos

Todos os operadores, além dos operadores $eq (igualdade) e $and (e), devem ser declarados explicitamente.

Operadores de combinação

Os operadores de combinação são usados para combinar seletores. Três operadores de combinação ($all, $allMatch e $elemMatch) ajudam a trabalhar com matrizes JSON, além dos operadores booleanos comuns encontrados na maioria das linguagens de programação.

Um operador de combinação usa um único argumento. O argumento é outro seletor ou uma matriz de seletores.

Operadores de combinação
Operador Argumento Propósito
$all Matriz Corresponderá a um valor de matriz se contiver todos os elementos da matriz de argumento.
$allMatch Seletor Corresponde e retorna todos os documentos que contêm um campo matricial no qual todos os elementos correspondem a todos os critérios de consulta especificados.
$and Matriz Corresponderá se todos os seletores na matriz corresponderem.
$elemMatch Seletor Corresponde e retorna todos os documentos que contêm um campo matricial com pelo menos um elemento que corresponde a todos os critérios de consulta especificados.
$nor Matriz Corresponderá se nenhum dos seletores na matriz corresponder.
$not Seletor Corresponderá se o seletor não corresponder.
$or Matriz Corresponderá se algum dos selecionadores na matriz corresponder. Todos os seletores devem usar o mesmo índice.

Exemplos de operadores de combinação

O operador $all

O operador $all corresponderá a um valor de matriz se contiver todos os elementos da matriz de argumento.

Veja o exemplo a seguir que usa o operador $all:

{
	"selector": {
		"genre": {
			"$all": ["Comedy","Short"]
		}
	},
	"fields": [
		"title",
		"genre"
	],
	"limit": 10
}

O operador $allMatch

O operador $allMatch corresponde e retorna todos os documentos que contêm um campo matricial no qual todos os elementos nesse campo matricial correspondem aos critérios de consulta fornecidos.

Veja o exemplo a seguir que usa o operador $allMatch:

{
    "genre": {
        "$allMatch": {
          "$eq": "Horror"
        }
    }
}

O operador $and

O operador $and corresponderá se todos os seletores da matriz corresponderem.

Veja o exemplo a seguir que usa o operador $and:

{
    "selector": {
        "$and": [
            {
                "year": {
                    "$in": [2014, 2015]
                }
            },
            {
                "genre": {
                     "$all": ["Comedy","Short"]
                 }
            }
        ]
    },
    "fields": [
        "year",
        "_id",
        "title"
    ],
    "limit": 10
}

O operador $elemMatch

O operador $elemMatch corresponde e retorna todos os documentos que contêm um campo matricial com pelo menos um elemento que corresponde aos critérios de consulta fornecidos.

Veja o exemplo a seguir que usa o operador $elemMatch:

{
	"selector": {
		"genre": {
			"$elemMatch": {
				"$eq": "Horror"
			}
		}
	},
	"fields": [
		"title",
		"genre"
	],
	"limit": 10
}

O operador $nor

O operador $nor corresponderá se o seletor não corresponder.

Veja o exemplo a seguir que usa o operador $nor:

{
	"selector": {
		"year": {
			"$gte": 1900,
			"$lte": 1910
		},
		"$nor": [
			{ "year": 1901 },
			{ "year": 1905 },
			{ "year": 1907 }
		]
	},
	"fields": [
		"title",
		"year"
	]
}

O operador $not

O operador $not corresponderá se o seletor não for resolvido para um valor de true.

Veja o exemplo a seguir que usa o operador $not:

{
	"selector": {
		"year": {
			"$gte": 1900,
			"$lte": 1903
		},
		"$not": {
			"year": 1901
		}
	},
	"fields": [
		"title",
		"year"
	]
}

O operador $or

O operador $or corresponderá se algum dos seletores na matriz corresponder.

Veja o exemplo a seguir que usa o operador $or:

{
	"selector": {
		"year": 1977,
		"$or": [
			{ "director": "George Lucas" },
			{ "director": "Steven Spielberg" }
		]
	},
	"fields": [
		"title",
		"director",
		"year"
	]
}

Operadores de condição

Os operadores de condição são específicos para um campo e são usados para avaliar o valor que é armazenado nesse campo. Por exemplo, o operador $eq corresponde quando o campo especificado contém um valor que é igual ao argumento fornecido.

Os operadores básicos de igualdade e desigualdade comuns à maioria das linguagens de programação são suportados. Alguns operadores de condição de "meta" também estão disponíveis.

Alguns operadores de condição aceitam qualquer conteúdo JSON válido como o argumento. Outros operadores de condição requerem que o argumento esteja em um formato JSON específico.

Requisitos de argumento do operador de condição
Tipo de operador Operador Argumento Propósito
(Des) igualdade $lt Qualquer JSON O campo é menor que o argumento.
$lte Qualquer JSON O campo é menor ou igual ao argumento.
$eq Qualquer JSON O campo é igual ao argumento.
$ne Qualquer JSON O campo não é igual ao argumento.
$gte Qualquer JSON O campo é maior ou igual ao argumento.
$gt Qualquer JSON O campo é maior que o argumento.
Object $exists Booleano Verifique se o campo existe ou não, não importa qual seja o seu valor.
$type Sequência Verifique o tipo de campo do documento. Os valores aceitos são null, boolean, number, string, array e object.
Matriz $in Matriz de valores JSON O campo de documentos deve existir na lista fornecida.
$nin Matriz de valores JSON O campo de documentos não deve existir na lista fornecida.
$size Integer Condição especial para corresponder ao comprimento de um campo matricial em um documento. Os campos não matriciais não podem corresponder a essa condição.
Diversos $mod [Divisor, Restante] Divisor e Restante são números inteiros positivos ou negativos. Valores não inteiros resultam em um status 404. Corresponde a documentos nos quais a expressão (field % Divisor == Remainder) é verdadeira e somente quando o campo de documento é um número inteiro.
$regex Sequência Um padrão de expressão regular para corresponder ao campo de documento. Corresponde apenas quando o campo é um valor de sequência e corresponde à expressão regular fornecida.

As expressões regulares não funcionam com índices, portanto, elas não devem ser usadas para filtrar conjuntos de dados grandes. No entanto, eles podem ser usados para restringir um partial index <find/partial_indexes>.

Exemplos de operadores de condição

O operador $lt

O operador $lt corresponderá se o conteúdo de campo especificado for menor que o argumento.

Veja o exemplo a seguir que usa o operador $lt com índice de texto total:

{
	"selector": {
		"year": {
			"$lt": 1900
		}
	},
	"sort": [
		"year:number",
		"title:string"
	],
	"fields": [
		"year",
		"title"
	]
}

Veja o exemplo a seguir que usa o operador $lt com um banco de dados que é indexado no campo year:

{
	"selector": {
		"year": {
			"$lt": 1900
		}
	},
	"sort": [
		"year"
	],
	"fields": [
		"year"
	]
}

O operador $lte

O operador $lte corresponderá se o conteúdo do campo especificado for menor ou igual ao argumento.

Veja o exemplo a seguir que usa o operador $lte com índice de texto total:

{
	"selector": {
		"year": {
			"$lte": 1900
		}
	},
	"sort": [
		"year:number",
		"title:string"
	],
	"fields": [
		"year",
		"title"
	]
}

Veja o exemplo a seguir que usa o operador $lte com um banco de dados que é indexado no campo year:

{
	"selector": {
		"year": {
			"$lte": 1900
		}
	},
	"sort": [
		"year"
	],
	"fields": [
		"year"
	]
}

O operador $eq

O operador $eq corresponderá se o conteúdo do campo especificado for igual ao argumento fornecido.

Veja o exemplo a seguir que usa o operador $eq com índice de texto total:

{
	"selector": {
		"year": {
			"$eq": 2001
		}
	},
	"sort": [
		"title:string"
	],
	"fields": [
		"title"
	]
}

Veja o exemplo a seguir que usa o operador $eq com um banco de dados que é indexado no campo year:

{
	"selector": {
		"year": {
			"$eq": 2001
		}
	},
	"sort": [
		"year"
	],
	"fields": [
		"year"
	]
}

O operador $ne

O operador $ne corresponderá se o conteúdo do campo especificado não for igual ao argumento fornecido.

O operador $ne não pode ser o elemento básico (nível mais baixo) em um seletor quando você usa um índice do tipo json.

Veja o exemplo a seguir que usa o operador $ne com índice de texto total:

{
	"selector": {
		"year": {
			"$ne": 1892
		}
	},
	"fields": [
		"year"
	],
	"sort": [
		"year:number"
	]
}

Veja o exemplo a seguir que usa o operador $ne com um índice primário:

{
	"selector": {
	"year": {
			"$ne": 1892
		}
	},
	"fields": [
		"year"
	],
	"limit": 10
}

O operador $gte

O operador $gte corresponderá se o conteúdo do campo especificado for maior ou igual ao argumento.

Veja o exemplo a seguir que usa o operador $gte com índice de texto total:

{
	"selector": {
		"year": {
			"$gte": 2001
		}
	},
	"sort": [
		"year:number",
		"title:string"
	],
	"fields": [
		"year",
		"title"
	]
}

Veja o exemplo a seguir que usa o operador $gte com um banco de dados que é indexado no campo year:

{
	"selector": {
		"year": {
			"$gte": 2001
		}
	},
	"sort": [
		"year"
	],
	"fields": [
		"year"
	]
}

O operador $gt

O operador $gt corresponderá se o conteúdo do campo especificado for maior que o argumento.

Veja o exemplo a seguir que usa o operador $gt com índice de texto total:

{
	"selector": {
		"year": {
			"$gt": 2001
		}
	},
	"sort": [
		"year:number",
		"title:string"
	],
	"fields": [
		"year",
		"title"
	]
}

Veja o exemplo a seguir que usa o operador $gt com um banco de dados que é indexado no campo year:

{
	"selector": {
		"year": {
			"$gt": 2001
		}
	},
	"sort": [
		"year"
	],
	"fields": [
		"year"
	]
}

O operador $exists

O operador $exists será correspondente se o campo existir, independentemente do seu valor.

Veja o exemplo a seguir que usa o operador $exists:

{
	"selector": {
		"year": 2015,
		"title": {
			"$exists": true
		}
	},
	"fields": [
		"year",
		"_id",
		"title"
	]
}

O operador $type

O operador $type requer que o campo de documento especificado seja do tipo correto.

Veja o exemplo a seguir que usa o operador $type:

{
	"selector": {
		  "year": {
			"$type": "number"
		}
	},
	"fields": [
		"year",
		"_id",
		"title"
	]
}

O operador $in

O operador $in requer que o campo de documentos exista na lista fornecida.

Veja o exemplo a seguir que usa o operador $in:

{
	"selector": {
		  "year": {
			"$in": [2010, 2015]
		}
	},
	"fields": [
		"year",
		"_id",
		"title"
	],
	"limit": 10
}

O operador $nin

O operador $nin requer que o campo do documento não exista na lista fornecida.

Veja o exemplo a seguir que usa o operador $nin:

{
	"selector": {
		  "year": {
			"$nin": [2010, 2015]
		}
	},
	"fields": [
		"year",
		"_id",
		"title"
	],
	"limit": 10
}

O operador $size

O operador $size corresponde ao comprimento de um campo matricial em um documento.

Veja o exemplo a seguir que usa o operador $size:

{
	"selector": {
		  "genre": {
			"$size": 4
		}
	},
	"fields": [
		"title",
		"genre"
	],
	"limit": 25
}

O operador $mod

O operador $mod corresponde a documentos nos quais a expressão (field % Divisor == Remainder) é verdadeira e somente quando o campo de documentos é um número inteiro. O Divisor e o Restante devem ser números inteiros. Eles podem ser números inteiros positivos ou negativos. Uma consulta em que o Divisor ou o Resto é um número não inteiro retorna um status 404.

Quando você usa valores inteiros negativos para o Divisor ou Resto, o operador IBM® Cloudant® for IBM Cloud® $mod usa divisão truncada. Tanto o operador Erlang rem modulo quanto o operador % em C, se comportam de maneira semelhante.

Veja o exemplo a seguir que usa o operador $mod:

{
	"selector": {
          "year": {
			"$mod": [100,0]
		}
	},
	"fields": [
		"title",
		"year"
	],
	"limit": 50
}

O operador $regex

O operador $regex corresponde quando o campo é um valor de sequência e corresponde à expressão regular fornecida.

Veja o exemplo a seguir que usa o operador $regex:

{
	"selector": {
		   "cast": {
			"$elemMatch": {
				"$regex": "^Robert"
			}
		}
	},
	"fields": [
		"title",
		"cast"
	],
	"limit": 10
}