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.

Note

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.

      The page shows results listed in groupings.

    3. To filter results more specifically, click Choose one or more resource types to filter the results. Then, type or choose one or more resource types to include in the filtered results. Filter options include only the resource types present in the full list of results.

    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 your 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 flags and variable options for CLI commands, see the Command Line Reference.

  • 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 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.