# Apono Query Language The Apono Query Language (AQL) provides a simple, intuitive syntax for filtering cloud resources, integrations, and permissions.

This reference documents query construction, available components, and common filtering examples. {% hint style="success" %} When you are first starting to build queries, you can quickly learn how to build them by following these steps: 1. On the [**Inventory**](https://app.apono.io/inventory) page, click **Basic**. 2. [Filter the resources](/docs/inventory/inventory.md#filter-resources). 3. Click **AQL**. The AQL syntax will appear in the code box. {% endhint %} *** ### **Syntax** The following is a basic AQL query. ```sql resource_type = "aws-rds-mysql" ``` AQL uses a simple **field-operator-value** pattern. ```sql field operator "value" ```

Component Description

field Attribute or tag to query

operator Comparative logic

Component	Description
field	Attribute or tag to query
operator	Comparative logic
value	Expected value for the field AQL values must be enclosed in double quotes (`""`). A backslash (`\`) can be used to escape special characters inside a string. AQL does not support embedded newlines inside string values and rejects single quotes (`''`).

value

Expected value for the field

AQL values must be enclosed in double quotes (""). A backslash (\) can be used to escape special characters inside a string.

AQL does not support embedded newlines inside string values and rejects single quotes ('').

#### field The `field` component specifies the attribute of your cloud resources to query. {% tabs %} {% tab title="Resource" %} {% hint style="warning" %} All resource field names are **case sensitive** and **strictly matched**. For example, when querying for a resource type (`resource_type`), AQL rejects **`R`**`esource_`**`T`**`ype` because the casing is incorrect and `resource_type`**`s`** because it does not match a supported field name. {% endhint %}

Field	Description	Supported operators	Example
resource_type	Resource type	Comparison, Lists, Logic	`resource_type = "aws-rds-mysql"`
resource_name	Human-readable display name for the resource	Comparison, String Matching, Lists, Logic	`resource_name contains "prod"`
resource_path	Hierarchical path within the integration	Comparison, String Matching, Lists, Logic	`resource_path contains "us-east-1"`
resource	Apono internal resource identifier	Comparison, Lists, Logic	`resource = "res_12345"`
resource_status	Current status	Comparison, Lists, Logic	`resource_status = "active"`
resource_source_id	Native identifier in the source system, such as an ARN	Comparison, String Matching, Lists, Logic	`resource_source_id = "arn:aws:iam::123:role/admin"`
resource_risk_level	Associated risk level	Comparison, Lists, Logic	`resource_risk_level = "high"`

{% endtab %} {% tab title="Permission" %} {% hint style="warning" %} All permission field names are **case sensitive** and **strictly matched**. For example, when querying for a permission name (`permission_name`), AQL rejects **`P`**`ermission_`**`N`**`ame` because the casing is incorrect and `permission_name`**`s`** because it does not match a supported field name. {% endhint %}

Field	Description	Supported operators	Example
permission_name	Human-readable display name for the permission	Comparison, String Matching, Lists, Logic	`permission_name = "ReadOnly"`
permission	Apono internal permission identifier	Comparison, Lists, Logic	`permission = "perm_12345"`
permission_risk_level	Permission risk level	Comparison, Lists, Logic	`permission_risk_level = "critical"`

{% endtab %} {% tab title="Integration" %} {% hint style="warning" %} The integration field name is **case sensitive** and **strictly matched**. For example, when querying for an integration (`integration`), AQL rejects **`I`**`ntegration` because the casing is incorrect and `integration`**`s`** because it does not match a supported field name. {% endhint %}

Field	Description	Supported operators	Example
integration	Apono internal Integration identifier	Comparison, Lists, Logic	`integration = "int_12345"`

{% endtab %} {% tab title="Metadata" %} {% hint style="warning" %} All metadata field names are **case sensitive** and **strictly matched**. For example, when querying for a resource tag (`resource_tag`), AQL rejects **`R`**`esource_`**`T`**`ag` because the casing is incorrect and `resource_tag`**`s`** because it does not match a supported field name. {% endhint %}

Field	Description	Supported operators	Example
resource_tag["key"]	Resource tags	Comparison, String Matching, Lists, Logic	`resource_tag["environment"] = "prod"`
resource_context["key"]	Resource context	Comparison, String Matching, Lists, Logic	`resource_context["region"] = "us-east-1"`
permission_context["key"]	Permission context	Comparison, String Matching, Lists, Logic	`permission_context["access"] = "write"`

{% endtab %} {% endtabs %} #### operator The `operator` component defines how to evaluate the `field` against the specified `value`. {% tabs %} {% tab title="Comparison" %} Basic operators that test for equality and inequality between values

Logic	Description	Example
=	Checks if values are the same	`resource_type = "aws-account-dynamodb-table"`
!=	Checks if values are different	`integration != "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`

{% endtab %} {% tab title="String Matching" %} Operators that perform case-sensitive text comparisons against literal string values {% hint style="warning" %} All string matching operators are **case sensitive**. For example, when checking if a literal string is contained (`contains`) as a substring, AQL rejects `CONTAINS` because the casing is incorrect. {% endhint %}

Logic	Description	Example
contains	Checks if a value contains another literal string as a substring	`(resource_tag["aws:cloudformation:stack-name"] contains "apono-cloudtrail")`
not_contains	Checks if a value does NOT contain a literal string as a substring	`permission_name not_contains "admin"`
starts_with	Checks if a value begins with a specific string	`resource_name starts_with "aws"`
ends_with	Checks if a value ends with a specific string	`(resource_tag["env"] ends_with "dev")`

{% endtab %} {% tab title="Lists" %} Operators that check if values exist within defined sets of options {% hint style="warning" %} All list operators are **case sensitive**. For example, when checking if a value is in a list (`in`), AQL rejects `IN` because the casing is incorrect. {% endhint %}

Logic Description Example

Logic	Description	Example
in (_)	Checks if the value is one of a list Use a comma-separated list enclosed in parentheses. Do not add a comma after the final item.	`resource_type in ("aws-account-dynamodb-table", "aws-account-s3", "aws-account-sns-topic")` `resource_source_id in ("arn:aws:s3:::bucket-a", "arn:aws:s3:::bucket-b")`
not_in (_)	Checks if the value is NOT one of a list Use a comma-separated list enclosed in parentheses. Do not add a comma after the final item.	`(resource_tag["aws:cloudformation:stack-name"] not_in ("apono-cloudtrail", "apono-doxy-dev"))`

in (_)

Checks if the value is one of a list

Use a comma-separated list enclosed in parentheses. Do not add a comma after the final item.

resource_type in ("aws-account-dynamodb-table", "aws-account-s3", "aws-account-sns-topic")

resource_source_id in ("arn:aws:s3:::bucket-a", "arn:aws:s3:::bucket-b")

not_in (_)

Checks if the value is NOT one of a list

Use a comma-separated list enclosed in parentheses. Do not add a comma after the final item.

(resource_tag["aws:cloudformation:stack-name"] not_in ("apono-cloudtrail", "apono-doxy-dev"))

{% endtab %} {% tab title="Logic" %} Operators that combine multiple conditions to create complex queries {% hint style="info" %} Logic operators are **not case** sensitive. {% endhint %}

Logic	Description	Example
and \| AND	Checks if both conditions are true	`resource_type = "aws-account-s3" AND permission_name = "admin"`
or \| OR	Checks if either condition is true	`resource_type = "aws-account-s3" OR resource_name contains "playground"`
not \| NOT	Negates a condition	`integration = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" and not resource_type = "aws-account-sns-topic"`

{% endtab %} {% endtabs %} #### Unsupported Operators not supported by AQL

Not supported	Description	Example
*	Wildcards	`resource_name = "prod-*"`
<, >, <=, >=	Numeric comparison	`resource_risk_level <= "high"`
^, $, +, ?	Regular expressions (regex)	`resource_name = "^prod"` `resource_name = "prod-?s"`
between	Ranges	`between "2024-01-01" and "2024-12-31"`
exists	Existence checks	`exists(resource_tag["owner"])`
null	Null checks	`resource_tag["owner"] = null`

*** ### Common Queries The following AQL queries demonstrate how to efficiently locate, audit, and manage cloud resources and permissions. They cover common use cases such as identifying high-risk assets, tracking access levels, and enforcing security policies. Use these queries as a foundation and customize them to fit your specific environment and compliance requirements. #### Resource Queries Queries focused on locating and filtering cloud infrastructure resources ```sql # Find production databases resource_type = "aws-rds-mysql" and resource_name contains "prod" # Find high-risk resources in specific region resource_risk_level = "high" and resource_context["region"] = "us-east-1" # Find resources by team ownership resource_tag["team"] = "platform" and resource_tag["environment"] = "prod" ``` #### Permission Queries Queries that manage and audit access control settings {% code overflow="wrap" %} ```sql # Find critical write permissions permission_risk_level = "critical" and permission_context["access"] = "write" # Find elevated permissions permission_risk_level in ("high","critical") and not permission_name contains "readonly" ``` {% endcode %} #### Combined Queries Advanced patterns that merge resource and permission conditions for precise access control ```sql # Find high-risk prod resources with write permissions resource_name contains "prod" and resource_risk_level = "high" and permission_context["access"] = "write" ``` *** ### Best Practices Follow these best practices to write AQL queries that are clear, efficient, and easy to modify. These guidelines improve readability, execution speed, and adaptability. #### Start with a specific condition AQL processes conditions from left to right. Starting with a specific filter improves efficiency. ```sql # Effective resource_type = "aws-rds-mysql" and resource_name contains "prod" # Less Efficient resource_name contains "prod" and resource_type = "aws-rds-mysql" ``` #### Use lists instead of multiple OR conditions When checking multiple values, `in (...)` is more concise and performs better than chaining multiple `or` conditions. {% code overflow="wrap" %} ```sql # Effective resource_type in ("aws-rds-mysql", "aws-account-s3", "aws-ec2-ssh") # Less efficient resource_type = "aws-rds-mysql" or resource_type = "aws-account-s3" or resource_type = "aws-ec2-ssh" ``` {% endcode %} #### Use parentheses to avoid ambiguity Without parentheses, complex conditions can be misinterpreted and return unexpected results. Grouping conditions explicitly ensures the query evaluates as intended. ```sql (resource_type = "aws-rds-mysql" and resource_name contains "prod") or (resource_type = "aws-account-s3" and resource_name contains "backup") ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.apono.io/docs/inventory/apono-query-language.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.