Oracle Cloud Infrastructure Documentation

Querying Resources

This topic describes how to find Oracle Cloud Infrastructure resources in your tenancy by performing a free text search or running a query. Queries let you find resources according to specific fields and conditions while free text searches locate resources with the desired text anywhere in the resource metadata.

Note

Supported Resources and Query Language Syntax

Search bases search results on supported resources. To see what Oracle Cloud Infrastructure services and resources Search supports, see the Supported Resources section of Overview of Search.

Furthermore, if free text search results do not produce the results you want, you might need to run a query using query language syntax. For more information about syntax for queries, see Search Language Syntax.

Using the Console

You can find resources by doing one of the following:

  • typing free-form text for a free text search
  • typing a query (based on resource query language syntax)
  • modifying a sample query

By default, text entered into the Search box is interpreted as a free text search.

To perform a free text search
To run a custom, free-form query
To run a sample query

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use the following operations to search for resources or find out what resources you can search for:

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 will find 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 your query produces results, the response will list the resources that match the resource type and tag that you specified. The response will look 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 additional 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.