OCI Search cheat sheet: find any resource by name, state, tag, compartment or creation time

You need to answer "where is it?" or "what do we have?" fast. Which compartment is that instance in? What was created in the last 24 hours? Which resources are missing a cost-center tag? OCI Search answers these across every compartment in a region without walking the compartment tree. This page lists the queries that come up most during operations work.

#Where to run queries

Search is regional. It returns resources in the region you're querying, so add --region to the CLI command, or switch region in the Console, to search somewhere else. Results only include resources you have permission to inspect.

#Query grammar in one block

query <type>[, <type>...] resources
  [return allAdditionalFields]
  [where <conditions>]
  [matching '<text>']
  [sorted by <field> asc|desc]

• <type> is a resource type such as instance, volume, vcn or user, or all.
• With no sorted by, results come newest first.
• String and date values go in single or double quotes.
• Whitespace and line breaks are ignored, so you can format long queries over several lines.

#Operators

In the query blocks below, lines starting with -- are labels for you. They aren't part of the query language, so don't paste them into Search.

Dates accept '2026-11-01T00:00:00Z', '2026-11-01 00:00:00 UTC', and relative values such as now - 24h (units s, m, h, d, w).

#Basic CLI pattern

oci search resource structured-search \
  --query-text "query instance resources where lifeCycleState = 'RUNNING'" \
  --query 'data.items[].{name:"display-name", state:"lifecycle-state", compartment:"compartment-id", id:identifier}' \
  --output table --all

--all pages through every result. The JMESPath --query keeps the output readable. Leave it off when you want the full JSON.

#Find by name

# Name contains "payments" (case-insensitive), any type
oci search resource structured-search --all --query-text \
  "query all resources where displayName =~ 'payments'"

# Exact name, instances only
oci search resource structured-search --all --query-text \
  "query instance resources where displayName = 'app-prod-01'"

# Free text: matches names, OCIDs, IPs and other indexed fields
oci search resource free-text-search --text "10.0.2.15"

Tip

Free-text search is the fastest way to find which resource an IP address or a partial OCID from a log line belongs to.

#Find by lifecycle state

query instance resources where lifeCycleState = 'RUNNING'

query instance resources where lifeCycleState = 'STOPPED'

query instance resources
  where lifeCycleState = 'TERMINATED' || lifeCycleState = 'TERMINATING'

Lifecycle values differ by resource type, for example AVAILABLE for volumes or ACTIVE for many networking resources. Run a query without the state filter first and check which values come back.

#Find by compartment

query all resources where compartmentId = 'ocid1.compartment.oc1..aaaa...'

query volume, bootvolume resources where compartmentId = 'ocid1.compartment.oc1..aaaa...'

This matches only resources directly in that compartment, not in its child compartments. It's useful before you delete a compartment. Run it in every subscribed region:

COMP=ocid1.compartment.oc1..aaaa...
for r in $(oci iam region-subscription list --query 'data[]."region-name"' --raw-output | tr -d '[]",'); do
  echo "== $r"
  oci search resource structured-search --region "$r" --all \
    --query-text "query all resources where compartmentId = '$COMP' && lifeCycleState != 'TERMINATED' && lifeCycleState != 'DELETED'" \
    --query 'data.items[].{type:"resource-type", name:"display-name", state:"lifecycle-state"}' --output table
done

#Find by creation time

-- Everything created in the last 24 hours, newest first
query all resources where timeCreated >= 'now - 24h' sorted by timeCreated desc

-- Instances created since a date
query instance resources where timeCreated >= '2026-10-01T00:00:00Z'

This is a quick first check after an unexpected cost spike or a security alert. Use the Audit log to find out who created something.

#Find by tags

-- Freeform tag
query all resources
  where (freeformTags.key = 'env' && freeformTags.value = 'prod')

-- Defined tag
query all resources
  where (definedTags.namespace = 'Operations' && definedTags.key = 'CostCenter' && definedTags.value = '1234')

-- Either of two defined tag values
query all resources
  where (definedTags.namespace = 'Operations' && definedTags.key = 'Env' && definedTags.value = 'prod')
     || (definedTags.namespace = 'Operations' && definedTags.key = 'Env' && definedTags.value = 'uat')

-- Always Free resources (system tag)
query all resources
  where systemTags.namespace = 'orcl-cloud' && systemTags.key = 'free-tier-retained' && systemTags.value = 'true'

Tag key and value matching ignores case. If your tenancy uses the default Oracle-Tags namespace, you can find resources by creator with definedTags.namespace = 'Oracle-Tags' && definedTags.key = 'CreatedBy' plus a value condition.

Warning

Search for missing tags isn't reliable with !=. A resource without the tag has nothing to compare against. To find untagged resources, export all resources of a type with return allAdditionalFields and filter the JSON, as shown below, or enforce tags with tag defaults and Security Zones.

#Discover the fields you can filter on

# Supported resource types and their names
oci search resource-type list --all --query 'data[].name' --output table

# Every indexed field for one type (CLI/SDK only, the Console can't show them all)
oci search resource structured-search --query-text \
  "query instance resources return allAdditionalFields where displayName = 'app-prod-01'"

Field names returned under additional-details can be used in where clauses for that type. Field names vary by resource type and change over time, so check them in your own output before you put a query in a script.

#Find untagged instances with jq

oci search resource structured-search --all --query-text \
  "query instance resources where lifeCycleState = 'RUNNING'" \
| jq -r '.data.items[]
    | select((."defined-tags".Operations.CostCenter // "") == "")
    | [."display-name", ."compartment-id"] | @tsv'

#Combine types and sort

-- Volumes and boot volumes in one list, oldest first
query volume, bootvolume resources sorted by timeCreated asc

-- Users and groups called admin
query group, user resources where displayName = 'administrator'

-- Instances with a maintenance reboot due
query instance resources where timeMaintenanceRebootDue = 'now'

#Quick reference

#Prevent it next time

• Apply a defined Owner, Env and CostCenter tag through tag defaults, so tag queries return complete answers.
• Save your common queries in a team runbook or as shell functions, with the region loop built in.
• Use naming conventions that put the environment and application in displayName. Then =~ queries become reliable.
• Check that on-call engineers have inspect permissions on all compartments. Search silently hides resources they can't see.