Documentación de Oracle Cloud Infrastructure

Sintaxis de lenguaje de búsqueda

En este tema se describen los aspectos básicos del lenguaje de consulta para la búsqueda. Se incluye una explicación sobre la sintaxis y las reglas para que pueda crear sus propias consultas. Las consultas aplican condiciones de búsqueda a tipos de recursos específicos y permiten ordenar los resultados. El lenguaje de consulta proporciona un control más matizado y explícito sobre los parámetros de búsqueda, lo que lo hace especialmente útil en casos en los que los cambios precisos en una consulta pueden producir resultados diferentes.

Si desea buscar en todos los tipos de recursos soportados y atributos de recursos y no necesita resultados de búsqueda ordenados, o si prefiere utilizar la interfaz de consola para especificar parámetros de búsqueda, no es necesario crear ninguna consulta. En su lugar, puede buscar una coincidencia parcial o exacta del texto de formato libre sin aplicar sintaxis de lenguaje de consulta a la búsqueda.

Cuando esté listo para ejecutar una consulta, consulte Consulta de recursos para obtener instrucciones.

Conceptos básicos sobre consultas

En los siguientes ejemplos se muestra la sintaxis básica de una consulta.

Para consultar los recursos que cumplen una o más condiciones descritas por una sentencia de condición que utiliza operadores de comparación:

query <resourceType> resources where <conditions>

Para consultar recursos que cumplan una o más condiciones y para incluir atributos de recursos ordenados en los resultados:

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

O bien, para consultar los recursos que tienen cualquier atributo con un valor que coincida con lo especificado:

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

La búsqueda ignora los espacios en blanco, la sangría y los saltos de línea. Las consultas de ejemplo incluyen sangría para mejorar la legibilidad. Con la finalidad de mostrar solo la sintaxis, los paréntesis angulares (<>) y el texto en cursiva indican variables, que pueden constar de una o más palabras clave.

En una consulta, las cláusulas incluyen lo siguiente:

  • query: (obligatoria) selecciona los recursos que se devolverán según las cláusulas posteriores. Las sentencias de la consulta siempre empiezan por la palabra query.
  • return: especifica los atributos de recursos que se deben incluir en la vista ampliada o mejorada de los resultados de búsqueda. Para obtener más información, consulte Atributos de devolución.
  • where: hace coincidir los recursos con las conditions especificadas. Para obtener más información, consulte Condiciones.
  • matching: hace coincidir los recursos con el texto especificado independientemente de si el texto coincide exactamente, coincide con el tipo de recurso o aparece en un atributo de recurso indexado. Para obtener más información, consulte Confrontación.
  • sorted by: ordena los recursos según fieldName en el orden especificado por la cláusula order. Sin esta cláusula, la búsqueda muestra los resultados por fecha de creación en orden descendente, mostrando en primer lugar los recursos más recientes. Para obtener más información, consulte Ordenación.

Las cláusulas son opcionales a menos que se indique lo contrario. Para fines de coincidencia, puede utilizar la cláusula where y la cláusula matching por separado o conjuntamente.

En la cláusula query, especifique la siguiente información:

  • resourceType: (obligatoria) especifica el tipo de recurso al que se aplican las siguientes cláusulas al ejecutar la consulta. Puede especificar el nombre del tipo de recurso (por ejemplo, database o group) u all. Si especifica all, la búsqueda busca coincidencias con el conditions especificado en todos los tipos de recursos. Puede consultar tipos de recursos individuales, pero no los de familia. Para obtener una lista de los tipos de recursos soportados, consulte la sección Recursos soportados de la Visión general de la búsqueda.
  • resources: (obligatoria) especifica que el texto que está enviando es una consulta de recurso.

Atributos de devolución

Para los usuarios del SDK o la CLI, la cláusula return indica qué atributos de recursos ampliados desea ver incluidos con los resultados de búsqueda devueltos por la consulta. Puede utilizar la cláusula return para forzar la devolución de atributos de recursos específicos o de todos los atributos de recursos en los resultados de búsqueda, lo que le proporciona más detalles sobre cada recurso.

Por defecto, los resultados de búsqueda muestran un conjunto limitado y común de atributos de recursos para cualquier recurso coincidente. En la consola, estos atributos de recursos incluyen el nombre mostrado, el tipo de recurso, el OCID, el compartimento, el estado del ciclo de vida y el tiempo creado. En el SDK o la CLI, los resultados de búsqueda de recursos básicos también incluyen el dominio de disponibilidad y cualquier etiqueta asociada al recurso. Cuando una consulta encuentra una coincidencia fuera de los atributos de recursos comunes, los resultados de búsqueda ampliados incluyen y resaltan los atributos específicos coincidentes junto con los resultados básicos. Con la cláusula return, puede obtener más detalles sobre la coincidencia de resultados de búsqueda incluso si la consulta no provoca una coincidencia en los atributos de recurso que desea ver.

En una consulta, la cláusula return consta de lo siguiente:

return <fieldName>

La palabra clave fieldName identifica un atributo de un recurso. Por ejemplo, cuando el tipo de recurso al que dirige la consulta es una instancia, la especificación de shape indica que desea ver la unidad de todas las instancias coincidentes. (Solo en el caso de instancias, fieldName puede identificar un atributo de un recurso relacionado, como la dirección IP privada en la asociación de VNIC de una instancia. Al especificar attachedVnic.privateIp, se indica que desea ver la dirección IP privada de la asociación entre una VNIC y una instancia).

Los detalles adicionales disponibles para un recurso concreto dependen de los atributos de recursos que se hayan indexado para el tipo de recurso. Para buscar los nombres de todos los atributos de recursos indexados para un tipo de recurso, utilice el SDK o la CLI para ejecutar una consulta que incluya la cláusula return, pero en lugar de especificar el nombre del campo, especifique que desea ver allAdditionalFields. Por ejemplo

query instance resources return allAdditionalFields

Esta consulta produce una respuesta que muestra todos los atributos de recursos indexados para el tipo de recurso de instancia. (La consola no puede mostrar estos otros campos, excepto los recursos de instancia cuando aplica el filtro de tipo de recurso, por lo que debe utilizar el SDK o la CLI para recuperar la información). En los resultados de búsqueda, los detalles adicionales disponibles (y la estructura de esa información) dependen del tipo de recurso coincidente. Además, debe tener el permiso necesario para ver los atributos de recurso que ha solicitado ver con la consulta.

Puede combinar la cláusula return con la cláusula where para obtener resultados con detalles específicos al tiempo que aplica una o más condiciones. Por ejemplo
query instance resources return allAdditionalFields where assignedEntityType = 'PRIVATE_IP'

Esta consulta produce una respuesta que muestra todos los atributos de recursos indexados para todos los recursos de instancia que tienen un campo assignedEntityType con el valor PRIVATE_IP.

Restricciones

Solo puede utilizar la cláusula return en un tipo de recurso a la vez. La consulta no puede especificar varios tipos de recursos si incluye la cláusula return. Sin embargo, si lo desea, puede especificar más de un campo para devolver para un tipo de recurso concreto.

No puede incluir tanto la palabra clave allAdditionalFields como los nombres de campo individuales en la misma consulta. Puede especificar la palabra clave allAdditionalFields o puede especificar más nombres de campo individuales, separados por comas.

Condiciones

La cláusula where aplica conditions que filtran los resultados de la búsqueda. Puede especificar una o más sentencias de condición. Para obtener más información sobre varias condiciones, consulte Agrupación de condiciones.

En una consulta, conditions consta de lo siguiente:

<fieldName> <operation> <value>

La palabra clave fieldName es el atributo de recurso con respecto al cual se evalúan las operation y las value seleccionadas de ese atributo. Cada campo se asocia a un tipo de campo. El tipo de campo indica el formato esperado para cualquier valor de ese campo. El tipo de operation que puede utilizar en una sentencia conditions depende del tipo de campo.

En la consulta conditions, una operation es un operador de comparación que se aplica a value en la sentencia. La palabra clave value hace referencia al valor de fieldName especificado. La búsqueda evalúa si el atributo especificado del tipo de recurso seleccionado coincide o no con value, según la operación. En una consulta, debe introducir cualquier valor de cadena o fecha-hora entre comillas de apertura y cierre simples rectas (ˈ) o comillas dobles (").

En la siguiente tabla se describen las operaciones soportadas para consultas de recursos:

Operación Descripción Tipos de campos soportados ¿Distingue entre mayúscula y minúscula? Ejemplo
=

Igual o coincidencia exacta para cadenas

Cadena, entero, racional, booleano, fecha-tiempo

No

 Si el valor introducido para value es ˈbackUpˈ, coincidirá con "backup", "BACKUP", "BackUp", "backUp", o cualquier otro tipo de variación en mayúsculas/minúsculas.
!=

No es igual a

Cadena, entero, racional, booleano, fecha-tiempo

No

 Si el valor introducido para value es ˈbackUpˈ, coincidirá con cualquier otro tipo de variación que no sea "backUp", "backup", o cualquier otro tipo de variación de mayúscula/minúscula. También coincidiría con resultados que no contenga los caracteres 'backup' en ese orden.
==

Estrictamente igual

Cadena

Sí

 Si el valor introducido para value es ˈbackUpˈ, solo coincidirá con "backUp" y con ninguna otra variación de mayúscula/minúscula.
!==

No es igual estrictamente

Cadena

Sí

 Si el valor introducido para value esˈbackUpˈ, coincidirá con "backup", "BACKup", o cualquier otro resultado, excepto "backUp", con esa combinación de mayúsculas/minúsculas exacta.
=~

Contiene

Cadena

No

 El valor introducido en value es ˈbackUpˈ,coincidirá con cualquier resultado que sea igual a "backup", "BACKUP", "BackUp", "backUp" o cualquier otra variación de mayúsculas/minúsculas o contenga dichos caracteres en ese orden, junto con otros caracteres.
>=

Mayor o igual que

Entero, racional, fecha-hora

No aplicable

 Para una consulta con size >= 5 como condición, todos los resultados tendrán un valor de 5 o superior en el campo denominado size.
>

Mayor que

Entero, racional, fecha-hora

No aplicable

 Para una consulta con size > 5 como condición, todos los resultados tendrán un valor superior a 5 en el campo denominado size.
<=

Menor que o igual a

Entero, racional, fecha-hora

No aplicable

 Para una consulta con size <= 5 como condición, todos los resultados tendrán un valor de 5 o inferior en el campo denominado size.
<

Menor que

Entero, racional, fecha-hora

No aplicable

 Para una consulta con size < 5 como condición, todos los resultados tendrán un valor inferior a 5 en el campo denominado size.

En la siguiente tabla, se muestran algunos ejemplos de atributos de recursos que pertenecen a cada categoría de tipos de campo admitidos. (Como se ha descrito anteriormente, el tipo de campo le indica el formato esperado para un campo determinado y el tipo de operation con el que puede emparejarlo en una sentencia conditions.)

En la tabla no se incluyen todos los ejemplos posibles para un tipo de campo determinado ni tampoco se incluyen ejemplos de cada tipo de recurso. Si desea saber qué formato espera el servicio Search para un atributo de recurso específico, puede utilizar la interfaz de línea de comandos o la API para obtener más información sobre los atributos de recursos. También puede consultar la documentación de la API. La documentación de la API incluye una referencia de cada tipo de recurso soportado que especifica atributos, sus tipos de campo y restricciones. Para obtener más información, consulte la sección sobre Recursos soportados de Visión general de la opción de búsqueda.

Tipo Ejemplo de atributos de recurso
Cadena Mostrar nombres, estados de ciclo de vida, dominios de disponibilidad, etiquetas, bloques CIDR y URL
Entero Tamaño o longitud de un recurso
Racional Almacenamiento de datos disponible
Booleano Si una función está activada o configurada, si un recurso está en buen estado, si un recurso es público o privado, si algo es la versión más reciente y si se permite algo.
Fecha y hora Fechas de creación, fechas de última actualización, fechas de último indexado y reinicios de mantenimiento programado

Condiciones de agrupación

Al incluir más de una sentencia de condición en una consulta, puede acotar los resultados según varios criterios. Puede agrupar condiciones mediante operadores lógicos && (ampersands para indicar un operador AND lógico), || (barras verticales, para indicar un operador OR lógico) o el operador IN lógico. Por ejemplo

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

En el ejemplo anterior, todos los resultados tienen LICENSE_INCLUDED como valor en el campo denominado licenseModel, un valor mayor que 40 para el campo denominado dataStoragePercentage y un valor en el campo lifecycleState que sea cualquier otro valor que no sea FAILED.

No puede combinar dos operadores lógicos diferentes en la misma consulta a menos que ajuste los paréntesis alrededor de un grupo de predicados. (De lo contrario, varias condiciones solo pueden usar el mismo operador lógico). Por ejemplo

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

En el ejemplo anterior, todos los resultados devueltos tienen LICENSE_INCLUDED como valor en el campo denominado licenseModel y un valor mayor que 40 para el campo denominado dataStoragePercentage o el valor de su campo lifecycleState es cualquier otro valor que no sea FAILED.

También se acepta el siguiente grupo:

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

En el ejemplo anterior, todos los resultados devueltos tienen LICENSE_INCLUDED como valor en el campo denominado licenseModel y un valor mayor que 40 como valor para el campo denominado dataStoragePercentage o cualquier valor que no sea FAILED para el valor del campo denominado lifecycleState.

Para aplicar varias condiciones en las que cada condición acepta más de un valor posible, el uso de un operador IN lógico puede simplificar una consulta. Por ejemplo, puede utilizar las siguientes condiciones:
licenseModel IN ('LICENSE_INCLUDED', 'BRING_YOUR_OWN_LICENSE') && dbWorkload IN ('OLTP', 'DW', 'AJD', 'APEX')
En el ejemplo anterior, todos los resultados devueltos tienen LICENSE_INCLUDED o BRING_YOUR_OWN_LICENSE como valor en el campo denominado licenseModel y un valor de OLTP, DW, AJD o APEX como valor en el campo denominado dbWorkload. El ejemplo anterior puede sustituir a condiciones de consulta más complejas, como las siguientes:
(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')
O incluso lo siguiente:
((licenseModel = 'LICENSE_INCLUDED' || licenseModel = 'BRING_YOUR_OWN_LICENSE') && (dbWorkload = 'OLTP' || dbWorkload = 'DW' || dbWorkload = 'AJD' || dbWorkload = 'APEX'))

En ambos ejemplos se utiliza el operador lógico OR para expresar de forma eficaz las mismas condiciones en términos más detallados que en el ejemplo que utiliza el operador lógico IN.

La búsqueda no realiza una evaluación de izquierda a derecha para reducir la ambigüedad o aclarar la intención.

Valores de fecha y hora

Puede especificar valores de fecha y hora mediante cualquiera de los siguientes formatos de cadena de patrón:

Formato Ejemplos Comentarios
<yyyy>-<MM>-<dd> <HH>:<mm>:<ss> <TimeZone>

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

 TimeZone es opcional. Si se omite TimeZone, se utilizará UTC.
<EEE>, <d> <MMM> <yyyy> <HH>:<mm>:<ss> <TimeZone>

'Tue, 19 Jun 2018 16:15:41 +0300', '19 June 2018 16:15:41'

 EEE es opcional. MMM también puede expresarse como MMMM. TimeZone también es opcional. Si se omite TimeZone, se utilizará UTC.
<yyyy>-<MM>-<dd>T<HH>:<mm>:<ss>Z

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

Horas en UTC 'T' y 'Z' son sensibles a mayúsculas/minúsculas.

Debe observar el espaciado. Interprete guiones, dos puntos, comas y los caracteres 'T' y 'Z' literalmente. Para interpretar valores de marcadores de posición en la tabla anterior, consulte la siguiente sintaxis de patrones:

Letra Componente de fecha u hora Presentación
a

Año

Año
M

Mes del año

Mes
d

Día del mes

Día
H Hora del día (de 00 a 23) Número
m Minuto de una hora Número
s Segundos de minuto Número
E Día de la semana Texto

Las letras de patrón de repetición indican la presentación exacta. Por ejemplo, 'HH' significa que debe usar '00' y no '0' para representar la medianoche. De forma similar, 'EEE' significa 'Mar' y no 'Martes'. Del mismo modo, al especificar 'MM' se debe usar '09' en lugar de '9' para representar el mes de septiembre.

TimeZone es opcional, pero en el formato elegido, puede especificar TimeZone de cualquiera de las siguientes formas:

  • Nombre. Puede especificar una zona horaria por su nombre, por ejemplo, GMT o PDT. Los valores son sensibles a mayúsculas/minúsculas.
  • Valor de desplazamiento de GMT. Puede especificar una zona horaria de acuerdo con su desplazamiento de GMT. Por ejemplo, GMT-08:00. Los valores son sensibles a mayúsculas/minúsculas.
  • Zona horaria ISO 8601. Puede especificar una zona horaria de acuerdo con los estándares de ISO 8601. Por ejemplo, -08, -0800, o -08:00.

En lugar de utilizar uno de los formatos anteriores, también puede especificar un valor de fecha-hora como la constante now. La constante now representa la hora actual al nivel de granularidad de segundos en un minuto.

Por último, puede agregar o restar intervalos de tiempo de cualquier valor de fecha y hora. Por ejemplo, puede consultar los recursos que se crearon dentro de los cinco minutos de un tiempo específico. La búsqueda soporta los siguientes intervalos de tiempo:

Letra Componente de fecha u hora
s

Segundos
m

Minutos
h

Horas
d Días
s Semanas

Para especificar un intervalo de tiempo en relación a un valor de fecha y hora, utilice uno de los siguientes formatos:

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

Coincidencia

Para fines de coincidencia, en lugar de o además de utilizar una cláusula where con conditions, puede que desee utilizar la cláusula matching. La cláusula matching obvia la necesidad de especificar conditions (que contiene un nombre de campo, una operación y un valor). Una cláusula matching consulta eficazmente todos los campos indexados aplicando el operador = (igual a) junto con el texto especificado. Sin embargo, esto no requiere una coincidencia exacta. Por ejemplo, la siguiente consulta utiliza una cláusula matching para comportarse igual que una búsqueda de texto libre:

query all resources matching 'instance'

La consulta ofrece resultados que coinciden con todos los recursos y atributos de recursos que contienen la palabra "instance".

La cláusula matching consulta todos los campos indexados para las coincidencias, pero ignora los caracteres especiales, incluida cualquier puntuación.

Orden

La última cláusula de una consulta de recurso es la cláusula sorted by y es opcional. La cláusula sorted by ordena los resultados devueltos por la búsqueda según el nombre del campo y los muestra según la opción order que especifique. Por defecto, si no se especifica el orden de clasificación, los resultados siempre se ordenan por fecha y hora de creación en orden descendente.

En la cláusula sorted by, puede especificar lo siguiente:

  • fieldName: campo que utiliza la búsqueda para ordenar los resultados. Puede especificar cualquier campo de cualquier recurso. Los recursos que no contienen el campo que especifique se enumeran después de los recursos que lo contienen.
  • order: puede especificar asc o desc. Al especificar asc, los resultados se mostrarán en orden ascendente. Al especificar desc, los resultados se mostrarán en orden descendiente.

Consulta de varios tipos de recursos

Puede consultar más de un tipo de recurso a la vez uniendo consultas. Cada consulta puede tener su propia cláusula condicional. Si las consultas que desea unir tienen condiciones "donde" diferentes, la sintaxis será diferente que cuando tiene consultas para varios tipos de recursos que comparten la misma condición "donde".

La sintaxis básica para una consulta de varios tipos de recursos es la siguiente:

query <resourceType>, <resourceType> resources

Por ejemplo

query group, user resources

La consulta de ejemplo anterior devuelve todos los grupos y todos los usuarios del arrendamiento.

A continuación, se muestra la sintaxis de una consulta para varios tipos de recursos con condiciones, pero donde las condiciones son iguales para todos los tipos de recursos:

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

Por ejemplo

query group, user resources where displayName = 'administrator'

La consulta de ejemplo anterior devuelve todos los grupos con el nombre mostrado"administrator" y todos los usuarios con el nombre mostrado"administrator", con cualquier variación de mayúsculas/minúsculas.

Si necesita aplicar condiciones diferentes a cualquier tipo de recurso, debe utilizar una palabra clave union en lugar de separar por comas consultas unidas. A continuación, se muestra la sintaxis de una consulta para varios tipos de recursos en los que algunos tipos de recursos comparten condiciones mientras que otros no:

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

Por ejemplo

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

El ejemplo anterior devuelve todos los grupos con el nombre mostrado"administrator" y todos los usuarios con el nombre mostrado"administrator", con cualquier variación de mayúsculas/minúsculas y todos los recursos del compartimento.

O, por ejemplo:

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

El ejemplo anterior devuelve todos los grupos y todos los compartimentos. También devuelve todos los usuarios con el nombre mostrado"administrador", con cualquier variación de mayúsculas/minúsculas.

También puede agregar la cláusula sorted by al final de la consulta para ordenar todos los resultados en orden ascendente o descendente.