Running a Custom, Free-Form Query

Free-form queries let you customize a search for resources by using structured query language that can specify conditions, resource attributes, and resource values that you want from results.

Queries support filtering and sorting resources through query language syntax. You effectively filter results by adding or removing clauses or changing the content of clauses. The only query you can perform that doesn't filter results is a query for everything.

For more information about syntax for advanced resource queries, see Search Language Syntax.

1. In the top navigation bar, click Search for resources, services, documentation, and Marketplace, and then select Advanced resource query.
2. In the query text box, enter a query that conforms to query language syntax, and then click Search. For more information about syntax, see Search Language Syntax.
3. To filter results more specifically, change the language of the query.
  
  Note
  
  In advanced query mode, while you can filter and sort results by changing the query language, you can't filter or sort results through the results list displayed in the Console. Also, if you switch to advanced query mode from basic search mode, by default, results are sorted by the time the resource was created. You can change to sorting results by best match by removing the sorted by clause in the query language.
The results are eventually consistent, but might not immediately include resources that you created recently. If you don't see the results that you expect, you can change to a different region or edit the query.
Use the oci search resource structured-search command and required parameters to use structured query language to find resources:
```
oci search resource structured-search --query-text "<query_text_using_query_language_syntax>"
```
For a complete list of parameters and values for CLI commands, see the CLI Command Reference. For information about the syntax for queries, see Search Language Syntax.

Run the SearchResources operation to use structured query language to find resources.

Example: Finding Instance Resources With a Specific Defined Tag

This section describes how to use the API to query for a specific type of resource based on the resource's defined tags.

The following query finds instances with a defined tag within the namespace "rqs", where the tag's key is "costcenter" and the key's value is "1234".

query
 instance resources
 where
 (definedTags.namespace = 'rqs' && definedTags.key = 'costcenter' && definedTags.value = '1234')

When you use the SearchResources operation to issue the query, the request will look similar to the following. (This example purposefully omits the authorization header and other headers.)

POST /20180409/resources
Host: query.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
  "type": "Structured",
  "query": "query instance resources where (definedTags.namespace = 'rqs' && definedTags.key = 'costcenter' && definedTags.value = '1234')",
  "matchingContextType": "HIGHLIGHTS"
}

If the query produces results, the response lists the resources that match the resource type and tag that you specified. The response looks similar to the following:

{
  "items" : [ {
    "resourceType" : "Instance",
    "identifier" : "ocid1.instance.oc1.phx.exampleawcbfhncvbh3siw2svbpgr3bopovy6hgnywfauxqo37ckdmr6hjya",
    "compartmentId" : "ocid1.tenancy.oc1..examplea46vssm7l5wsk5qa7cvbl63ctajep4bh6lv4vaifauxz6ec7jzg4q",
    "timeCreated" : "2018-10-31T22:48:47.855Z",
    "displayName" : "service-pkgs",
    "availabilityDomain" : "ABCd:PHX-AD-1",
    "lifecycleState" : "RUNNING",
    "freeformTags" : { },
    "definedTags" : {
      "rqs" : {
        "costcenter" : "1234"
      }
    },
    "searchContext" : null
  }, {
    "resourceType" : "Instance",
    "identifier" : "ocid1.instance.oc1.phx.exampleanb3poce6z4omcvbzw66epp3pvbbww6hq7e2jfaux2lxvi3daxhra",
    "compartmentId" : "ocid1.compartment.oc1..examplea43m3udlwrzwmbcvbk5hm3umk2khgfhjcgdttawjlfauxuqwsjiya",
    "timeCreated" : "2018-10-09T23:35:30.167Z",
    "displayName" : "prod-test",
    "availabilityDomain" : "ABCd:PHX-AD-2",
    "lifecycleState" : "RUNNING",
    "freeformTags" : { },
    "definedTags" : {
      "rqs" : {
        "costcenter" : "1234"
      }
    },
    "searchContext" : null
  }, {
    "resourceType" : "Instance",
    "identifier" : "ocid1.instance.oc1.phx.examples7cz4z6b5hpdly2cvb56obhaiy4gvh2hdpz4akq4fauxpakvlqgya",
    "compartmentId" : "ocid1.tenancy.oc1..examplea46vssm7l5wsk5qa7cvbl63ctajep4bh6lv4fauxf4iz6ec7jzg4q",
    "timeCreated" : "2018-06-12T19:45:24.945Z",
    "displayName" : "BackupTest",
    "availabilityDomain" : "ABCd:PHX-AD-3",
    "lifecycleState" : "STOPPED",
    "freeformTags" : { },
    "definedTags" : {
      "rqs" : {
        "costcenter" : "1234"
      }
    },
    "searchContext" : null
  }, {
    "resourceType" : "Instance",
    "identifier" : "ocid1.compartment.oc1..exampleaexfjsiad7gbi6r4hvmcvbk3a5hgkvutlswf54ulfauxks4p2jasq",
    "compartmentId" : "ocid1.tenancy.oc1..examplea46vssm7l5cvb5qa7gg5l63ctajep4bh6lv4fauxf4iz6ec7jzg4q",
    "timeCreated" : "2018-06-12T19:25:16.942Z",
    "displayName" : "personal_abc",
    "availabilityDomain" : "ABCd:PHX-AD-2",
    "lifecycleState" : "TERMINATED",
    "freeformTags" : { },
    "definedTags" : {
      "rqs" : {
        "costcenter" : "1234"
      }
    },
    "searchContext" : null
  }, {
    "resourceType" : "Instance",
    "identifier" : "ocid1.compartment.oc1..examplealrskzczjqmrb3cvbj4yxdvqxahhffauxtu24tk5dhikoff4uliha",
    "compartmentId" : "ocid1.tenancy.oc1..examplea46vssm7l5wsk5qa7gg5l63cvbjep4bh6lv4fauxf4iz6ec7jzg4q",
    "timeCreated" : "2018-11-29T23:40:29.005Z",
    "displayName" : "test_unused",
    "availabilityDomain" : null,
    "lifecycleState" : "AVAILABLE",
    "freeformTags" : { },
    "definedTags" : {
      "rqs" : {
        "costcenter" : "1234"
      }
    },
    "searchContext" : null
  } ]
}

With these results, you can take more action, if needed. For more information about a resource type, such as its attributes, see its reference page in the API Reference Guide. For the reference pages of resource types that have been indexed for Search, see Supported Resources.

Oracle Cloud Infrastructure Documentation

Running a Custom, Free-Form Query

Example: Finding Instance Resources With a Specific Defined Tag