Documentação do Oracle Cloud Infrastructure

Sintaxe de Linguagem do Serviço Search

Este tópico descreve os fundamentos da linguagem de consulta do serviço Search, incluindo uma explicação de sintaxe e regras para que você possa criar suas próprias consultas. As consultas aplicam condições de pesquisa a tipos de recursos específicos e permitem classificar resultados. A linguagem de consulta oferece um controle mais explícito e detalhado sobre os parâmetros de pesquisa, tornando-a especialmente útil nos casos em que alterações precisas em uma consulta podem gerar resultados diferentes.

Se você quiser pesquisar em todos os tipos de recursos e atributos de recursos suportados e não precisar de resultados de pesquisa ordenados, ou se preferir usar a interface da Console para especificar parâmetros de pesquisa, não será necessário construir uma consulta. Em vez disso, você pode pesquisar uma correspondência parcial ou exata de texto de formato livre sem aplicar a sintaxe de linguagem de consulta à pesquisa.

Quando estiver pronto para executar uma consulta, consulte Pesquisando Recursos para obter instruções.

Fundamentos sobre Consulta

Os exemplos a seguir mostram a sintaxe básica de uma consulta.

Para consultar recursos que atendam a uma ou mais condições descritas por uma instrução de condição que usa operadores de comparação:

query <resourceType> resources where <conditions>

Para consultar recursos que atendem a uma ou mais condições e para incluir atributos de recursos classificados nos resultados:

query <resourceType> resources return <fieldName> where <conditions> sorted by <fieldName> <order>

Ou, para consultar recursos que tenham qualquer atributo com um valor correspondente ao que você especificar:

query <resourceType> resources return <fieldName> matching <keywords>

O serviço Search ignora espaço em branco, recuo e quebras de linha. As consultas de amostra incluem recuo para melhorar a legibilidade. Para fins de demonstração apenas de sintaxe, sinais de maior e menor (<>) e texto em itálico indicam variáveis, que podem consistir em uma ou mais palavras-chave.

Em uma consulta, as cláusulas incluem o seguinte:

  • query - ( Necessário) Seleciona quais recursos retornar com base nas cláusulas posteriores. As instruções de consulta sempre começam com a palavra query.
  • return: especifica quais atributos de recursos incluir na exibição expandida ou aprimorada dos resultados da pesquisa. Para obter mais informações, consulte Retornar Atributos.
  • where - Corresponde os recursos às conditions especificadas. Para obter mais informações, consulte Condições.
  • matching - Corresponde recursos ao texto especificado, independentemente de o texto corresponder exatamente, corresponder ao tipo de recurso ou aparecer em um atributo de recurso indexado. Para obter mais informações, consulte Correspondência.
  • sorted by - Ordena os recursos de acordo com fieldName na ordem especificada por order. Sem esta cláusula, a Pesquisa lista os resultados pela data de criação em ordem decrescente, com os recursos mais recentes listados primeiro. Para obter mais informações, consulte Classificação.

As cláusulas são opcionais, a menos que indicado em contrário. Para fins de correspondência, é possível usar a cláusula where e a cláusula matching separadamente ou juntas.

Na cláusula query, especifique as seguintes informações:

  • resourceType - (Obrigatório) Especifica o tipo de recurso ao qual as próximas cláusulas se aplicam ao executar a consulta. Você pode especificar o nome do tipo de recurso (por exemplo, database ou group) ou all. Se você especificar all, a Pesquisa procurará correspondências com o conditions especificado em todos os tipos de recursos. Você pode consultar tipos de recursos individuais, mas não tipos de família. Para obter uma lista de tipos de recursos suportados, consulte a seção Recursos Suportados da Visão Geral do Serviço Search.
  • resources - ( Necessário) Especifica que o texto que você está enviando é uma consulta de recurso.

Atributos de Devolução

Para usuários do SDK ou da CLI, a cláusula return indica quais atributos de recursos estendidos você deseja ver incluídos nos resultados da pesquisa retornados pela consulta. Você pode usar a cláusula return para forçar o retorno de atributos de recursos específicos ou de todos os atributos de recursos nos resultados da pesquisa, fornecendo mais detalhes sobre cada recurso.

Por padrão, os resultados da pesquisa exibem um conjunto limitado e comum de atributos de recursos para qualquer recurso correspondente. Na Console, esses atributos de recursos incluem o nome para exibição, o tipo de recurso, o OCID, o compartimento, o estado do ciclo de vida e o horário de criação. No SDK ou na CLI, os resultados básicos da pesquisa de recursos também incluem o domínio de disponibilidade e quaisquer tags associadas ao recurso. Quando uma consulta encontra uma correspondência fora dos atributos de recursos comuns, os resultados da pesquisa expandida incluem e destacam os atributos correspondentes específicos ao lado dos resultados básicos. Com a cláusula return, você pode obter mais detalhes sobre os resultados da pesquisa correspondentes, mesmo que a consulta não cause uma correspondência nos atributos de recursos que você deseja ver.

Em uma consulta, a cláusula return consiste no seguinte:

return <fieldName>

A palavra-chave fieldName identifica um atributo de um recurso. Por exemplo, quando o tipo de recurso direcionado pela consulta é uma instância, especificar shape indica que você deseja ver a forma de todas as instâncias correspondentes. (Apenas no caso de instâncias, o fieldName pode identificar um atributo de um recurso relacionado, como o endereço IP privado no anexo VNIC de uma instância. Especificar attachedVnic.privateIp indica que você deseja ver o endereço IP privado da conexão entre uma VNIC e uma instância.)

Os detalhes adicionais disponíveis para um recurso específico dependem de quais atributos de recurso foram indexados para o tipo de recurso. Para localizar os nomes de todos os atributos de recursos indexados para um tipo de recurso, use o SDK ou a CLI para executar uma consulta que inclua a cláusula return, mas em vez de especificar o nome do campo, especifique que você deseja ver allAdditionalFields. Por exemplo:

query instance resources return allAdditionalFields

Essa consulta produz uma resposta que mostra todos os atributos de recursos indexados para o tipo de recurso de instância. (A Console não pode exibir esses outros campos, exceto recursos da instância quando você aplica o filtro de tipo de recurso, e é por isso que você deve usar o SDK ou a CLI para recuperar as informações.) Nos resultados da pesquisa, os detalhes adicionais disponíveis (e a estrutura dessas informações) dependem do tipo de recurso correspondente. Além disso, você deve ter a permissão necessária para ver os atributos de recursos que solicitou para ver com sua consulta.

Você pode combinar a cláusula return com a cláusula where para obter resultados com detalhes específicos e, ao mesmo tempo, aplicar uma ou mais condições. Por exemplo:
query instance resources return allAdditionalFields where assignedEntityType = 'PRIVATE_IP'

Essa consulta produz uma resposta que mostra todos os atributos de recursos indexados para todos os recursos de instância que têm um campo assignedEntityType com um valor de PRIVATE_IP.

Restrições

Você só pode usar a cláusula return em um tipo de recurso de cada vez. A consulta não poderá especificar vários tipos de recursos se você incluir a cláusula return. Se quiser, porém, você pode especificar mais de um campo a ser retornado para um tipo de recurso específico.

Não é possível incluir a palavra-chave allAdditionalFields e os nomes de campo individuais na mesma consulta. É possível especificar a palavra-chave allAdditionalFields ou especificar ou mais nomes de campos individuais, separados por vírgulas.

Condições

A cláusula where aplica conditions que filtra os resultados retornados pela Pesquisa. Você pode especificar uma ou mais instruções de condição. Para obter mais informações sobre várias condições, consulte Agrupamento de Condições.

Em uma consulta, conditions consistem no seguinte:

<fieldName> <operation> <value>

A palavra-chave fieldName é o atributo de recurso em relação ao qual a operation e o value escolhido desse atributo são avaliados. Cada campo é associado a um tipo de campo. O tipo de campo informa o formato esperado para qualquer valor nesse campo. O tipo de operation que você pode usar em uma instrução conditions depende do tipo de campo.

Nas conditions de consulta, uma operation é um operador de comparação que se aplica ao value na instrução. A palavra-chave value se refere ao valor do fieldName especificado. O Search avalia se o atributo especificado do tipo de recurso escolhido corresponde ou não ao value, de acordo com a operação. Em uma consulta, você deve colocar qualquer string ou valor de data/hora ao abrir e fechar aspas simples retas (ˈ) ou aspas duplas (").

A tabela a seguir descreve as operações suportadas para consultas de recursos:

Operação Descrição Tipos de Campos Suportados Faz distinção entre maiúsculas e minúsculas? Exemplo
=

Uma correspondência igual ou exata de strings

String, número inteiro, número racional, Booliano, data-hora

Não

 Se o value fosse ˈbackUp', ele corresponderia a "backup", "BACKUP", "BackUp", "backUp" ou qualquer outra variação entre maiúsculas e minúsculas.
!=

Não é igual

String, número inteiro, número racional, Booliano, data-hora

Não

 Se o value fosse ˈbackUp', ele corresponderia a qualquer coisa que não fosse igual a "backUp", "backup", ou qualquer outra variação entre maiúsculas e minúsculas. Ele também corresponderia a qualquer coisa que não contivesse os caracteres 'backup' nessa ordem.
==

Estritamente igual a

String

Sim

 Se o value fosse 'backUp', ele corresponderia apenas a "backUp" e a nenhuma outra variação entre maiúsculas e minúsculas.
!==

Estritamente não é igual

String

Sim

 Se o value fosse ˈbackUpˈ, ele corresponderia a "backup", "BACKUP" ou a qualquer outra coisa, exceto "backUp", com essa distinção exata entre maiúsculas e minúsculas.
=~

Contém

String

Não

 Se o value fosse ˈbackUpˈ, ele corresponderia a qualquer coisa que fosse igual a "backup", "BACKUP", "BackUp", "backUp" ou a qualquer outra variação de maiúsculas e minúsculas ou que contivesse esses caracteres nessa ordem, junto com outros caracteres.
>=

Maior ou igual a

Número inteiro, número racional, data-hora

Não aplicável

 Para uma consulta em que você tem size >= 5 como a condição, todos os resultados têm um valor 5 ou mais no campo com o nome tamanho.
>

Maior que

Número inteiro, número racional, data-hora

Não aplicável

 Para uma consulta em que você tem size > 5 como a condição, todos os resultados têm um valor maior que 5 no campo com o nome tamanho.
<=

Menor ou igual a

Número inteiro, número racional, data-hora

Não aplicável

 Para uma consulta em que você tem size <= 5 como a condição, todos os resultados têm um valor de 5 ou menos no campo com o nome tamanho.
<

Menor que

Número inteiro, número racional, data-hora

Não aplicável

 Para uma consulta em que você tem size < 5 como a condição, todos os resultados têm um valor de 5 ou menos no campo com o nome tamanho.

A tabela a seguir lista alguns exemplos de atributos de recursos que pertencem a cada categoria de tipos de campo suportados. (Como descrito anteriormente, o tipo de campo informa o formato esperado para um determinado campo e o tipo de operation com o qual você pode combiná-lo em uma instrução conditions.)

A tabela não inclui todos os exemplos possíveis de um determinado tipo de campo nem exemplos de cada tipo de recurso. Se quiser saber em que formato o serviço de Pesquisa espera para um atributo de recurso específico, você poderá usar a interface de linha de comando ou a API para saber mais sobre atributos de recursos. Você também pode consultar a documentação da API. A documentação da API inclui uma referência para cada tipo de recurso suportado que especifica atributos, seus tipos de campo e quaisquer restrições. Para obter mais informações, consulte a seção Recursos Suportados da Visão Geral do Serviço Search.

Tipo Exemplo de Atributos do Recurso
String Exiba nomes, estados do ciclo de vida, domínios de disponibilidade, tags, blocos CIDR e URLs
Inteiro Tamanho ou comprimento de um recurso
Racional Armazenamento de dados disponível
Booliano Se um recurso está ativado ou configurado, se um recurso está íntegro, se um recurso é público ou privado, se algo é a versão mais recente e se algo é permitido
Data-hora Datas de criação, datas da última atualização, datas da última indexação e reinicializações de manutenção programadas

Agrupando Condições

Incluindo mais de uma instrução de condição em uma consulta, você pode refinar os resultados de acordo com vários critérios. Você pode agrupar condições usando os operadores lógicos && (e comercial, para indicar um E lógico), || ( barras verticais, para indicar um OU lógico) ou o operador lógico IN. Por exemplo:

licenseModel = 'LICENSE_INCLUDED' && dataStoragePercentage > 40 && lifecycleState != 'FAILED'

No exemplo anterior, todos os resultados têm LICENSE_INCLUDED como o valor no campo com o nome licenseModel, um valor maior que 40 para o campo com o nome dataStoragePercentage e um valor no campo lifecycleState que não seja FAILED.

Não é possível combinar dois operadores lógicos diferentes na mesma consulta, a menos que você coloque parênteses em torno de um grupo de predicados. (Caso contrário, várias condições poderão usar apenas o mesmo operador lógico.) Por exemplo:

(licenseModel = 'LICENSE_INCLUDED' && dataStoragePercentage > 40) || lifecycleState != 'FAILED'

No exemplo anterior, todos os resultados retornados têm LICENSE_INCLUDED como o valor no campo com o nome licenseModel e um valor maior que 40 para o campo com o nome dataStoragePercentage ou o valor do campo lifecycleState é qualquer coisa que não seja FAILED.

O seguinte grupo também é aceitável:

licenseModel = 'LICENSE_INCLUDED' && (dataStoragePercentage > 40 || lifecycleState != 'FAILED')

No exemplo anterior, todos os resultados retornados têm LICENSE_INCLUDED como o valor no campo com o nome licenseModel e um valor maior que 40 como o valor do campo com o nome dataStoragePercentage ou qualquer coisa que não seja FAILED para o valor do campo com o nome lifecycleState.

Para aplicar várias condições em que cada condição aceita mais de um valor possível, o uso de um operador lógico IN pode simplificar uma consulta. Por exemplo, você pode usar as seguintes condições:
licenseModel IN ('LICENSE_INCLUDED', 'BRING_YOUR_OWN_LICENSE') && dbWorkload IN ('OLTP', 'DW', 'AJD', 'APEX')
No exemplo anterior, todos os resultados retornados têm LICENSE_INCLUDED ou BRING_YOUR_OWN_LICENSE como o valor no campo chamado licenseModel e um valor de OLTP, DW, AJD ou APEX como o valor no campo chamado dbWorkload. O exemplo anterior pode substituir condições de consulta mais complexas, como as seguintes:
(licenseModel = 'LICENSE_INCLUDED' && dbWorkload = 'OLTP') || (licenseModel = 'BRING_YOUR_OWN_LICENSE' && dbWorkload = 'OLTP') || (licenseModel = 'LICENSE_INCLUDED' && dbWorkload = 'DW') || (licenseModel = 'BRING_YOUR_OWN_LICENSE' && dbWorkload = 'DW') || (licenseModel = 'LICENSE_INCLUDED' && dbWorkload = 'AJD') || (licenseModel = 'BRING_YOUR_OWN_LICENSE' && dbWorkload = 'AJD') || (licenseModel = 'LICENSE_INCLUDED' && dbWorkload = 'APEX') || (licenseModel = 'BRING_YOUR_OWN_LICENSE' && dbWorkload = 'APEX')
Ou mesmo o seguinte:
((licenseModel = 'LICENSE_INCLUDED' || licenseModel = 'BRING_YOUR_OWN_LICENSE') && (dbWorkload = 'OLTP' || dbWorkload = 'DW' || dbWorkload = 'AJD' || dbWorkload = 'APEX'))

Esses dois exemplos usam o operador lógico OU para expressar efetivamente as mesmas condições em termos mais verbosos do que o exemplo que usa o operador lógico IN.

A pesquisa não faz avaliação da esquerda para a direita para reduzir a ambiguidade ou esclarecer a intenção.

Valores de Data e Hora

Você pode especificar valores de data e hora usando qualquer um dos seguintes formatos de string padrão:

Formato Exemplos Comentários
<yyyy>-<MM>-<dd> <HH>:<mm>:<ss> <TimeZone>

'2018-06-19 16:15:41 PDT', '2018-06-19 16:15:41 -08:00'

 TimeZone é opcional. Se TimeZone for omitido, será usado o UTC.
<EEE>, <d> <MMM> <yyyy> <HH>:<mm>:<ss> <TimeZone>

'Ter, 19 Jun 2018 16:15:41 +0300', '19 Junho 2018 16:15:41'

 EEE é opcional. MMM também pode ser expresso como MMMM. TimeZone também é opcional. Se TimeZone for omitido, será usado o UTC.
<yyyy>-<MM>-<dd>T<HH>:<mm>:<ss>Z

'2018-06-19T16:15:41Z'

Hora em UTC. 'T' e 'Z' diferenciam maiúsculas de minúsculas.

Você deve observar o espaçamento. Interprete traços, dois-pontos, vírgulas e os caracteres 'T' e 'Z' literalmente. Para interpretar os valores de placeholder na tabela anterior, consulte a seguinte sintaxe de padrão:

Letra Componente de Data ou Hora Apresentação
y

Ano

Ano
M

Mês do ano

Mês
d

Dia do mês

Dia
H Hora do dia (de 00 a 23) Número
m Minuto da hora Número
s Segundos no minuto Número
E Dia da semana Texto

Letras de padrão repetidas indicam sua apresentação exata. Por exemplo, 'HH' significa que você deve usar '00' e não '0' para representar meia-noite. Da mesma forma, 'EEE' significa 'Ter' e não 'Terça-feira'. Da mesma forma, 'MM' requer '09' em vez de '9' para representar o mês de setembro.

TimeZone é opcional, mas no formato escolhido, é possível especificar TimeZone de uma das seguintes formas:

  • Nome. Você pode especificar um fuso horário por seu nome, como GMT ou PDT. Os valores diferenciam maiúsculas de minúsculas.
  • Valor de deslocamento GMT. Você pode especificar um fuso horário de acordo com seu deslocamento GMT. Por exemplo, GMT-08:00. Os valores diferenciam maiúsculas de minúsculas.
  • Fuso horário ISO 8601. Você pode especificar um fuso horário de acordo com os padrões ISO 8601. Por exemplo, -08, -0800 ou -08:00.

Em vez de usar um dos formatos anteriores, também é possível especificar um valor de data/hora como a constante now. A constante now representa a hora atual para o nível de granularidade de segundos em um minuto.

Por último, é possível adicionar ou subtrair intervalos de tempo de qualquer valor de data/hora. Por exemplo, você pode consultar recursos que foram criados em até cinco minutos de um tempo específico. O serviço Search suporta os seguintes intervalos de tempo:

Letra Componente de Data ou Hora
s

Segundos
m

Minutos
h

Horas
d Dias
w Semanas

Para especificar um intervalo de tempo em relação a um valor de data-hora, use um dos seguintes formatos:

  • agora - 3h
  • 2018-06-19 16:15:41 PDT + 1h

Correspondência

Para fins de correspondência, em vez de ou além de usar uma cláusula where com conditions, talvez você queira usar a cláusula matching. A cláusula matching obvia a necessidade de especificar conditions (que contêm um nome de campo, operação e valor). Uma cláusula matching consulta efetivamente todos os campos indexados aplicando o operador = (igual a) com o texto especificado. No entanto, ela faz isso sem exigir uma correspondência exata. Por exemplo, a consulta a seguir usa uma cláusula matching para se comportar da mesma forma que uma pesquisa de texto livre:

query all resources matching 'instance'

A consulta produz resultados que correspondem a todos os recursos e atributos de recursos que contêm a palavra "instance".

A cláusula matching consulta todos os campos indexados para correspondências, mas ignora caracteres especiais, incluindo qualquer pontuação.

Classificado por

A última cláusula de uma consulta de recurso é a cláusula sorted by e é opcional. A cláusula sorted by ordena os resultados retornados pelo serviço Search com base no nome do campo e os lista de acordo com a order que você especificar. Por padrão, se você não especificar a ordem de classificação, os resultados serão sempre classificados por data/hora de criação em ordem crescente.

Na cláusula sorted by, é possível especificar o seguinte:

  • fieldName - O campo que o serviço Search usa para classificar os resultados. Você pode especificar qualquer campo de qualquer recurso. Os recursos que não contêm o campo especificado são listados após os recursos que o contêm.
  • order - Você pode especificar asc ou desc. A especificação de listas asc resulta em ordem ascendente. A especificação de listas desc resulta em ordem descendente.

Consultando Vários Tipos de Recursos

Você pode consultar mais de um tipo de recurso por vez unindo consultas. Cada consulta pode ter sua própria cláusula condicional. Se as consultas que você deseja associar tiverem condições "onde" distintas, a sintaxe será diferente de quando você tiver consultas para vários tipos de recursos que compartilham a mesma condição "where".

A sintaxe básica para uma consulta para vários tipos de recursos é a seguinte:

query <resourceType>, <resourceType> resources

Por exemplo:

query group, user resources

A consulta de exemplo anterior retorna todos os grupos e todos os usuários na tenancy.

Veja a seguir a sintaxe de uma consulta para vários tipos de recursos com condições, mas quando as condições são as mesmas para todos os tipos de recursos:

query <resourceType>, <resourceType> resources where <conditions>

Por exemplo:

query group, user resources where displayName = 'administrator'

A consulta de exemplo anterior retorna todos os grupos com o nome para exibição "administrator" e todos os usuários com o nome para exibição "administrator", com qualquer variação de maiúsculas/minúsculas.

Se você precisar aplicar outras condições a qualquer tipo de recurso, use uma palavra-chave union, em vez da separação por vírgula entre as consultas associadas. Veja a seguir a sintaxe de uma consulta para vários tipos de recursos em que alguns tipos de recursos compartilham condições e outros não:

query <resourceType>, <resourceType> resources where <conditions> union <resourceType> resources

Por exemplo:

query group, user resources where displayName = 'administrator' union compartment resources

O exemplo anterior retorna todos os grupos com o nome para exibição "administrator" e todos os usuários com o nome para exibição "administrator", com qualquer variação de maiúsculas/minúsculas e todos os recursos de compartimento.

Ou, por exemplo:

query group resources union user resources where displayName = 'administrator' union compartment resources

O exemplo anterior retorna todos os grupos e todos os compartimentos. Ele também retorna todos os usuários com o nome para exibição "administrator", com qualquer variação de maiúsculas/minúsculas.

Opcionalmente, você pode adicionar a cláusula sorted by ao final da consulta para ordenar todos os resultados em ordem crescente ou decrescente.