Exploring the search and query features of Oracle Cloud Infrastructure command line interface

December 11, 2020 | 4 minute read
Seshadri Dehalisan
Distinguished Cloud Architect
Text Size 100%:

Oracle Cloud Infrastructure (OCI) provides a command line interface (CLI) that provides the same core capabilities as the OCI Console, extends the Console functionality, and facilitates developers and other user groups to automating the entire process of controlling, managing, and reporting through scripts. This blog aims to highlight one of the powerful yet least used features of OCI CLI: search, query, and reporting capabilities. These capabilities become critical, especially for cloud architects and cloud operations, to manage your OCI footprint at scale and when you have to deal with large amounts of output.

OCI also offers a plethora of options for automation, configuration management, cloud analytics, and reporting. Oracle Resource Manager and Terraform using OCI providers great options for developing immutable infrastructure as code (Iac), while OCI CLI provides excellent custom scripting and reporting options.

While you can read the documentation for yourself, I will focus on exemplifying a few key features related to the blog’s core theme. OCI CLI can generate outputs in the following formats with the output flag.

Output type Description
JSON The output is formatted as JSON string and is the default format; JSON is program-friendly but not human-friendly.
Table The output is formatted as a table using the characters +|- to form cell borders. It typically presents in an easier-to-read, human-friendly format.
--raw-output You can supply this argument to the CLI if you know that the output is a single string value; surrounding quotes are removed for you in the output.

Use case

Let’s start with a practical use case. You’re asked to list all the block volumes that exceed the size of 120 GB for a given compartment and region. You can use the SDK or the built-in features of OCI CLI with simple shell scripting. Compartments are foundational building blocks to organize and isolate your OCI resources.

for i in $(oci iam compartment list --compartment-id-in-subtree TRUE --all --query 'data[*].id' --profile us-ashburn-1|sed 's/\"//g;s/,//g'|egrep -v -e "\[" -e "\]")
for adomain in $(oci iam availability-domain list --query 'data[*].name' --profile us-ashburn-1|egrep -v -e "\[" -e "\]"|sed 's/\"//g;s/\,//g');
oci bv boot-volume list --profile us-ashburn-1 --compartment-id $i --availability-domain $adomain \
--query 'data[?"size-in-gbs" > `120`].{deviceID:id,size:"size-in-gbs"}' \
--output table|sed -n '4,$p'|egrep -v "^\+";
oci bv volume list --profile us-ashburn-1 --compartment-id $i --availability-domain $adomain \
--query 'data[?"size-in-gbs" > `120`].{deviceID:id,size:"size-in-gbs"}' \
--output table|sed -n '4,$p'|egrep -v "^\+";

This command gives you the following output:

Now, let’s dissect this script to understand the power that the CLI brings to the table.

Query 1

oci iam compartment list --compartment-id-in-subtree TRUE --all --query 'data[*].id' --profile us-ashburn-1

This query lists all the parent compartments and their subtrees. With query ‘data[*].id’, we are filtering only the OCID of the compartment. To know more about OCIDs, see the Resource Identifier documentation.

Query 2

Now that the compartment lists are available, let’s get the list of availability domain names.

oci iam availability-domain list --query 'data[*].name

Without the query arguments, the output has copious information about the availability domains, such as name, comparment_id, and OCID. We’re interested only in the availability domain name, and we get it by using JMESPath. JMESPath is the de facto query language for JSON. For details on JMESPath, see the documentation. Here, the argument query conforms to JMESPath query patterns. We select all data arrays and selectively displaying the required columns.

Query 3

Now that we’ve seen the basics of selecting en masse, we can explore ways to filter and look for storage volumes greater than 120 GB with the following command.

oci bv boot-volume list --profile us-ashburn-1 --compartment-id $i --availability-domain $adomain \
--query 'data[?"size-in-gbs"> `120`]

Here, ?“size-in-gbs”> `120` refers to the filtering and outputs those tuples that exceed 120 GB only. The string [?” size-in-gbs”?>`120`] acts as a where clause and filters out the volumes that are less than the provided number. The possibilities are endless, and you can use them in script.

Yet another interesting use case

If you’re asked to list all the instances in stopped or terminated status, you need to identify all the compartments and recursively list the instances in the previous states. Or you can use the following command:

oci search resource structured-search --query-text "QUERY instance resources where lifeCycleState = 'TERMINATED'||lifeCycleState = 'STOPPED'"

Then, you get the following output:

The JSON output is more machine reader-friendly than human reader-friendly. We can make the display readable by using the following output option of “table”:

oci search resource structured-search \
--query-text "QUERY instance resources where lifeCycleState = 'TERMINATED'||lifeCycleState = 'STOPPED'"
--query 'data.items[*].{ad:"availability-domain",instance:"identifier"}' --output table

Now, the following output is more human friendly:

Here, we’re using structured search. You can also use free-form search.


When using OCI CLI, you need to consider the following leading practices:

  • OCI CLI operations except get are not idempotent.

  • If subsequent operations depend on the completion of the current CLI command, use the appropriate wait-for-state flag with the required status, such as succeeded or failed.

  • Qualify at the appropriate compartment levels when you use recursive operations. Remember, compartments can be six levels deep.

  • For significant data retrievals, favor server-side filtering over client-side (JMESPath).

As shown in this posting, OCI CLI is not only powerful, but if used appropriately, it also provides great scripting and custom solutions capability for cloud architects and cloud operations. Happy scripting with Oracle Cloud Infrastructure CLI.

Seshadri Dehalisan

Distinguished Cloud Architect

Sesh is a Distinguished Cloud Architect. His passion is in leveraging technology to enable business outcome especially in the areas of MLOps and Cloud Native solutions. He has an MBA from University of Minnesota and a bachelor's in engineering.

Previous Post

Oracle and Accenture: Better Together, Putting the Us in Trust

Elena Hoffman | 5 min read

Next Post

How I passed the Oracle Cloud Infrastructure Foundations 2020 Certified Associate exam

Alexa Morales | 2 min read