Querying Resources, Services, and Documentation

This topic describes different ways you can use Search.

You can find Oracle Cloud Infrastructure resources in your tenancy by performing a free text search or running a query. A free text search locates resources with the desired text anywhere in the resource metadata. An advanced query lets you find resources according to specific fields and conditions. When finding resources, both free text searches and queries rely on resource indexing and the indexed attributes for a given resource type. Search also scopes resource results to the currently selected region.

Although queries can only be used to find resources, you can use free text searches to help you locate pages in the Console or help in the documentation. A free text search looks for search terms in the display names of Console pages and lists pages according to where they appear within services in the tenancy. A free text search can also find search terms in the Oracle Cloud Infrastructure Getting Started Guide and Oracle Cloud Infrastructure User Guide documentation. The results for both these types of searches depend on the language, but not the region.

Note

Supported Resources and Using Advanced Resource Queries

The search results that you see reflect what Search considers supported resources. To see what Oracle Cloud Infrastructure services and resources Search supports, see the Supported Resources section of Overview of Search.

Furthermore, if you don't find the resource you want or expect when you submit a free text search, you might need to run a query constructed using query language syntax. For more information about syntax for advanced queries, see Search Language Syntax. (For a documentation search, if a free text search doesn't produce the content results you expect, you might try a plural or singular form of one or more search terms or a different, supported language.)

Using the Console

You can find resources, services, or documentation by doing one of the following:

  • typing free-form text for a free text search
  • reusing recent search terms
  • typing a query (for resources only)
  • modifying a sample query

By default, text entered into the Search for resources, services, and documentation box is interpreted as a free text search.

To run a custom, free-form query to find a resource
  1. In the top navigation bar, click Search for resources, services, and documentation, and then click Advanced Resource Query.
  2. In the query text box, type a query using query language syntax, and then click Search.

  3. The list shows results in groupings. From here, you can filter results more specifically: click Choose one or more resource types to filter the results, and then type or choose one or more resource types to include in filtered results. Filter options only include resource types present in the full list of results.

  4. (Optional) If you do not see the results that you expect, you can change to a different region or edit your query.

Results are eventually consistent, but might not immediately include resources that you created very recently.

To run a sample query to find a resource
  1. In the top navigation bar, click Search for resources, services, and documentation, and then click Advanced Resource Query.
  2. Click Select Sample Query, and then click one of the listed sample queries. For an explanation of sample queries, see Sample Queries.

  3. Verify that the query language in the query text box satisfies your needs. Change all example values. Add, delete, or modify clauses, as appropriate, and then click Search.

  4. The list shows results in groupings. From here, you can filter results more specifically: click Choose one or more resource types to filter the results, and then type or choose one or more resource types to include in filtered results. Filter options only include resource types present in the full list of results.

  5. (Optional) If you do not see the results that you expect, you can change to a different region or edit your query.

Results are eventually consistent, but might not immediately include resources that you created very recently.

To reuse recent search terms
  1. In the top navigation bar, click Search for resources, services, and documentation.
  2. Under Recent searches, click one of five recent search terms. (Recent searches only include the five most recent free text searches, not advanced searches that use the structured query language.)

  3. Under one of the categories of search results, click a result. (To see all results on a full page instead, click View all next to the category name.)

  4. (Optional) If you do not see the results that you expect, you can change to a different region (if searching for a resource), change to a different language (if searching for a service or documentation), view a different category of search results, or edit your search terms. If searching for a resource, you can also refine your search with a query by clicking Advanced Resource Query. Then, follow the instructions in To run a custom, free-form query or To run a sample query.

  5. (Optional) If you chose to view results on a full page, the list shows results with the best matches at the beginning of the list. However, you can also do the following:

    • If you chose the Resources category specifically, you can sort results, expand individual results to see the matching text, or you can filter results more specifically. To filter results more specifically, click Choose one or more resource types to filter the results, and then type or choose one or more resource types to include.
    • For the Services category, you can only filter or sort results. To filter results more specifically, click Choose one or more service groups to filter the results, and then type or choose the service group to include.
    • Similarly, for the Documentation category, you can only filter or sort results. To filter results more specifically, click Choose one or more topics to filter the results. (Here, "topic" refers to the subject matter rather than the topic title.)

    For any category, filter options only include resource types, service groups, or documentation presented in the full list of results.

Results are eventually consistent, but might not immediately include resources that you created very recently.

Using the Command Line Interface (CLI)

For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see the Command Line Reference.

To see what resource-types you can run a query for

Open a command prompt and run oci search resource-type list to see what resource-types you can run a query for:

oci search resource-type list

For example:

oci search resource-type list --all
To see what resource attributes you can query for a given resource-type

Open a command prompt and run oci search resource-type get to see what attributes you can search for a given resource-type:

oci search resource-type get --name <resource-type_name>

You must specify the resource-type by its indexed name. Pay attention to capitalization. For example:

oci search resource-type get --name VolumeBackup
To perform a free text search

Open a command prompt and run oci search resource free-text-search to search the text of all searchable resource-types:

oci search resource free-text-search

For example:

oci search resource free-text-search --text <text_to_search_for>
To run a custom, free-form query to find a resource

Open a command prompt and run oci search resource structured-search to run an advanced resource query:

oci search resource structured-search --query-text "<query_text_using_query_language_syntax>"

For example:

oci search resource structured-search --query-text "query user resources"

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:

In addition to finding supported resources with ListResourceTypes, you can also find what attributes each resource supports for search.

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.