# How Do I Write Policies?

OPA is purpose built for reasoning about information represented in structured
documents. The data that your service and its users publish can be inspected and
transformed using OPA’s native query language Rego.

## <a name="what-is-rego"/>What is Rego?

Rego was inspired by [Datalog](https://en.wikipedia.org/wiki/Datalog), which is
a well understood, decades old query language. Rego extends Datalog to support
structured document models such as JSON.

Rego queries are assertions on data stored in OPA. These queries can be used to
define policies that enumerate instances of data that violate the expected state
of the system.

## <a name="why-use-rego"/>Why use Rego?

Use Rego for defining policy that is easy to read and write.

Rego focuses on providing powerful support for referencing nested documents and
ensuring that queries are correct and unambiguous.

Rego is declarative so policy authors can focus on what queries should return
rather than how queries should be executed. These queries are simpler and more
concise than the equivalent in an imperative language.

Like other applications which support declarative query languages, OPA is able
to optimize queries to improve performance.

## <a name="the-basics"/>The Basics

This section introduces the main aspects of Rego.

The simplest rule is a single expression and is defined in terms of a [Scalar Value](#scalar-values):

```ruby
pi = 3.14159
```

Rules define the content of documents. We can query for the content of the `pi` document generated by the rule above:

```ruby
> pi
3.14159
```

Rules can also be defined in terms of [Composite Values](#composite-values):

```ruby
rect = {"width": 2, "height": 4}
```

The result:

```ruby
> rect
{
  "height": 4,
  "width": 2
}
```

Many expressions are defined in terms of [Equality](#equality). These expressions can be thought of as assertions. The simplest example of a rule containing an equality expression involves two scalar values:

```ruby
v { "hello" = "world" }
```

We can evaluate `v` to check if it is equal to true:

```ruby
> v = true
false
```

The order of operands in an equality expression does not matter. The result is the same:

```ruby
> true = v
false
```

If we evaluate `v` on its own, the REPL prints `undefined` because the body of the rule never evaluates to `true`. As a result, the document generated by the rule is not defined.

```ruby
> v
undefined
```

We can define rules in terms of [Variables](#variables) as well:

```ruby
t { x = 42; y = 41; x > y }
```

The formal syntax uses the semicolon character `;` to separate expressions. Rule
bodies can separate expressions with newlines and omit the semicolon:

```
t2 {
    x = 42
    y = 41
    x > 1
}
```

When evaluating rule bodies, OPA searches for variable bindings that make all of
the expressions true. There may be multiple sets of bindings that make the rule
body true. The rule body can be understood intuitively as:

```
expression-1 AND expression-2 AND ... AND expression-N
```

The rule itself can be understood intuitvely as:

```
rule-name IS value IF body
```

If the **value** is omitted, it defaults to **true**.

When we query for the contents of `t` we see the obvious result:

```ruby
> t
true
```

The order of expressions in a rule does not affect the document’s content:

```ruby
s {
    x > y
    y = 41
    x = 42
}
```

The query result is the same:

```ruby
> s
true
```

Rego [References](#references) help you refer to nested documents. For example:

```ruby
sites = [{"name": "prod"}, {"name": "smoke1"}, {"name": "dev"}]

r { sites[i].name = "prod" }
```

The rule `r` above asserts that there exists (at least) one document within `sites` where the `name` attribute equals `"prod"`.

The result:

```ruby
> r
true
```

We can generalize the example above with a rule that defines a set document instead of a boolean document:

```ruby
q[name] { sites[i].name = name }
```

When we query for `q` we obtain a set of names:

```ruby
> q[x]
+----------+
|    x     |
+----------+
| "prod"   |
| "smoke1" |
| "dev"    |
+----------+
```

We can re-write the rule `r` from above to make use of `q`. We will call the new rule `p`:

```ruby
p { q["prod"] }
```

The result will be the same:

```ruby
> p
true
```

Rules which have arguments can be queried with input values:

```ruby
> q["smoke2"]
undefined
> q["dev"]
true
```

If you made it this far, congratulations!

This section introduced the main aspects of Rego. The rest of this document
walks through each part of the language in more detail.

For a concise reference, see the [Language
Reference](/documentation/references/language) document.

## <a name="scalar-values"></a> Scalar Values

Scalar values are the simplest type of term in Rego. Scalar values can be [Strings](#strings), numbers, booleans, or null.

Documents can be defined solely in terms of scalar values. This is useful for defining constants that are referenced in multiple places. For example:

```ruby
greeting   = "Hello"
max_height = 42
pi         = 3.14159
allowed    = true
sentinel   = null
```

These documents can be queried like any other:

```ruby
> greeting
"Hello"
> max_height
42
> pi
3.14159
> allowed
true
> sentinel
null
```

## <a name="strings"></a> Strings

Rego supports two different types of syntax for declaring strings. The first is likely to be the most familiar: characters surrounded by double quotes.
In such strings, certain characters must be escaped to appear in the string, such as double quotes themselves, backslashes, etc. See the [Language
Reference](/documentation/references/language) for a formal definition.

The other type of string declaration is a raw string declaration. These are made of characters surrounded by backticks (`` ` ``), with the exception
that raw strings may not contain backticks themselves. Raw strings are what they sound like: escape sequences are not interpreted, but instead taken
as the literal text inside the backticks. For example, the raw string `` `hello\there` `` will be the text "hello\there", not "hello" and "here"
separated by a tab.  Raw strings are particularly useful when constructing regular expressions for matching, as it eliminates the need to double
escape special characters.

A simple example is a regex to match a valid Rego variable. With a regular string, the regex is `"[a-zA-Z_]\\w*"`, but with raw strings, it becomes `` `[a-zA-Z_]\w*` ``.

## <a name="composite-values"></a> Composite Values

Composite values define collections. In simple cases, composite values can be treated as constants like [Scalar Values](#scalar-values):

```ruby
cube = {"width": 3, "height": 4, "depth": 5}
```

The result:

```ruby
> cube.width
3
```

Composite values can also be defined in terms of [Variables](#variables) or [References](#references). For example:

```ruby
> a = 42; b = false; c = null; d = {"a": a, "x": [b, c]}
+----+-------+------+---------------------------+
| A  |   B   |  C   |             D             |
+----+-------+------+---------------------------+
| 42 | false | null | {"a":42,"x":[false,null]} |
+----+-------+------+---------------------------+
```

By defining composite values in terms of variables and references, rules can define abstractions over raw data and other rules.

### <a name="sets"/>Sets

In addition to arrays and objects, Rego supports set values. Sets are unordered
collections of unique values. Just like other composite values, sets can be
defined in terms of scalars, variables, references, and other composite values.
For example:

```ruby
> s = {cube.width, cube.height, cube.depth}; count(s, n)
+---+---------+
| n |    s    |
+---+---------+
| 3 | [5,4,3] |
+---+---------+
```

> Set documents are collections of values without keys. OPA represents set
documents as arrays when serializing to JSON or other formats that do not
support a set data type. The important distinction between sets and arrays or
objects is that sets are unkeyed while arrays and objects are keyed, i.e., you
cannot refer to the index of an element within a set.

When comparing sets, the order of elements does not matter:

```
> {1,2,3} = {3,1,2}
true
```

Because sets are unordered, variables inside sets must be unified with a ground
value outside of the set. If the variable is not unified with a ground value
outside the set, OPA will complain:

```ruby
> {1,2,3} = {3,x,2}
1 error occurred: 1:1: rego_unsafe_var_error: var x is unsafe
```

Because sets share curly-brace syntax with objects, and an empty object is
defined with `{}`, an empty set has to be constructed with a different syntax:

```ruby
> count(set(), n)
+---+
| n |
+---+
| 0 |
+---+
```

## <a name="variables"></a> Variables

Variables are another kind of term in Rego. They appear in both the head and body of rules.

Variables appearing in the head of a rule can be thought of as input and output of the rule. Unlike many programming languages, where a variable is either an input or an output, in Rego a variable is simultaneously an input and an output. If a query supplies a value for a variable, that variable is an input, and if the query does not supply a value for a variable, that variable is an output.

For example:

```ruby
sites = [
    {"name": "prod"},
    {"name": "smoke1"},
    {"name": "dev"}
]

q[name] { sites[i].name = name }
```

In this case, we evaluate `q` with a variable `x` (which is not bound to a value). As as result, the query returns all of the site names.

```ruby
> q[x]
+----------+
|    x     |
+----------+
| "prod"   |
| "smoke1" |
| "dev"    |
+----------+
```

On the other hand, if we evaluate `q` with an input value for `name` we can determine whether `name` exists in the document defined by `q`:

```ruby
> q["smoke2"]
undefined
> q["dev"]
true
```

Variables appearing in the head of a rule must also appear in a non-negated equality expression within the same rule. This property ensures that if the rule is evaluated and all of the expressions evaluate to true for some set of variable bindings, the variable in the head of the rule will be defined.

## <a name="references"></a> References

Referenced are used to access nested documents.

The examples in this section use the data defined in the [Examples](#examples) section.

The simplest reference contains no variables. For example, the following reference returns the hostname of the second server in the first site document from our example data:

```ruby
> sites[0].servers[1].hostname
"helium"
```

References are typically written using the “dot-access” style. The canonical form does away with `.` and closely resembles dictionary lookup in a language such as Python:

```ruby
> sites[0]["servers"][1]["hostname"]
"helium"
```

Both forms are valid, however, the dot-access style is typically more readable. Note that there are four cases where brackets must be used:

  1. String keys containing characters other than `[a-z]`, `[A-Z]`, `[0-9]`, or `_` (underscore).
  1. Non-string keys such as numbers, booleans, and null.
  1. Variable keys which are described later.
  1. Composite keys which are described later.

References are always prefixed with a variable that identifies the root
document. In the example above this is `p`. The root document may be:

  * a local variable inside a rule.
  * a rule inside the same package.
  * a document stored in OPA.
  * a documented temporarily provided to OPA as part of a transaction.

### <a name="variable-keys"/>Variable Keys

References can include variables as keys. References written this way are used to select a value from every element in a collection.

The following reference will select the hostnames of all the servers in our
example data:

```ruby
> sites[i].servers[j].hostname
+---+---+------------------------------+
| i | j | sites[i].servers[j].hostname |
+---+---+------------------------------+
| 0 | 0 | "hydrogen"                   |
| 0 | 1 | "helium"                     |
| 0 | 2 | "lithium"                    |
| 1 | 0 | "beryllium"                  |
| 1 | 1 | "boron"                      |
| 1 | 2 | "carbon"                     |
| 2 | 0 | "nitrogen"                   |
| 2 | 1 | "oxygen"                     |
+---+---+------------------------------+
```

Conceptually, this is the same as the following imperative (Python) code:

```python
def hostnames(sites):
    result = []
    for site in sites:
        for server in site.servers:
            result.append(server.hostname)
    return result
```

In the reference above, we effectively used variables named `i` and `j` to iterate the collections. If the variables are unused outside the reference, we prefer to replace them with an underscore (`_`) character. The reference above can be rewritten as:

```ruby
> sites[_].servers[_].hostname
+------------------------------+
| sites[_].servers[_].hostname |
+------------------------------+
| "hydrogen"                   |
| "helium"                     |
| "lithium"                    |
| "beryllium"                  |
| "boron"                      |
| "carbon"                     |
| "nitrogen"                   |
| "oxygen"                     |
+------------------------------+
```

The underscore is special because it cannot be referred to by other parts of the rule, e.g., the other side of the expression, another expression, etc. The underscore can be thought of as a special iterator. Each time an underscore is specified, a new iterator is instantiated.

> Under the hood, OPA translates the `_` character to a unique variable name that does not conflict with variables and rules that are in scope.

### <a name="composite-keys"/>Composite Keys

References can include [Composite Values](#composite-values) as keys if the key is being used to refer into a set. Composite keys may not be used in refs
for base data documents, they are only valid for references into virtual documents.

This is useful for checking for the presence of composite values within a set, or extracting all values within a set matching some pattern.
For example:

```ruby
> s = {[1, 2], [1, 4], [2, 6]}
> s[[1, 2]]
[
  1,
  2
]
> s[[1, x]]
+---+
| x |
+---+
| 2 |
| 4 |
+---+
```

### <a name="multiple-expressions"/>Multiple Expressions

Rules are often written in terms of multiple expressions that contain references to documents. In the following example, the rule defines a set of arrays where each array contains an application name and a hostname of a server where the application is deployed.

```ruby
apps_and_hostnames[[name, hostname]] {
    apps[i].name = name
    apps[i].servers[_] = server
    sites[j].servers[k].name = server
    sites[j].servers[k].hostname = hostname
}
```

The result:

```ruby
> apps_and_hostnames[x]
+----------------------+
|          x           |
+----------------------+
| ["web","hydrogen"]   |
| ["web","helium"]     |
| ["web","beryllium"]  |
| ["web","boron"]      |
| ["web","nitrogen"]   |
| ["mysql","lithium"]  |
| ["mysql","carbon"]   |
| ["mongodb","oxygen"] |
+----------------------+
```

Don’t worry about understanding everything in this example right now. There are just two important points:

  1. Several variables appear more than once in the body. When a variable is used in multiple locations, OPA will only produce documents for the rule with the variable bound to the same value in all expressions.
  2. The rule is joining the `apps` and `sites` documents implicitly. In Rego (and other languages based on Datalog), joins are implicit.

### <a name="self-joins"/>Self-Joins

Using a different key on the same array or object provides the equivalent of self-join in SQL. For example, the following rule defines a document containing apps deployed on the same site as `"mysql"`:

```ruby
same_site[apps[k].name] {
    apps[i].name = "mysql"
    apps[i].servers[_] = server
    sites[j].servers[_].name = server
    sites[j].servers[_].name = other_server
    server != other_server
    apps[k].servers[_] = other_server
}
```

The result:

```ruby
> same_site[x]
+-------+
|   x   |
+-------+
| "web" |
| "web" |
| "web" |
| "web" |
+-------+
```

## <a name="comprehensions"></a> Comprehensions

Comprehensions provide a concise way of building [Composite Values](#composite-values) from sub-queries.

Like [Rules](#rules), comprehensions consist of a head and a body. The body of a comprehension can be understood in exactly the same way as the body of a rule, that is, one or more expressions that must all be true in order for the overall body to be true. When the body evaluates to true, the head of the comprehension is evaluated to produce an element in the result.

The body of a comprehension is able to refer to variables defined in the outer body. For example:

```ruby
> region = "west"; names = [name | sites[i].region = region; sites[i].name = name]
+-----------------+--------+
|      names      | region |
+-----------------+--------+
| ["smoke","dev"] | "west" |
+-----------------+--------+
```

In the above query, the second expression contains an [Array Comprehension](#array-comprehensions) that refers to the `region` variable. The region variable will be bound in the outer body.

> When a comprehension refers to a variable in an outer body, OPA will reorder expressions in the outer body so that variables referred to in the comprehension are bound by the time the comprehension is evaluated.

Comprehensions are similar to the same constructs found in other languages like Python. For example, we could write the above comprehension in Python as follows:

```ruby
# Python equivalent of Rego comprehension shown above.
names = [site.name for site in sites if site.region = "west"]
```

Comprehensions are often used to group elements by some key. A common use case for comprehensions is to assist in computing aggregate values (e.g., the number of containers running on a host).

### <a name="array-comprehensions"></a> Array Comprehensions

Array Comprehensions build array values out of sub-queries. Array Comprehensions have the form:

```ruby
[ <term> | <body> ]
```

For example, the following rule defines an object where the keys are application names and the values are hostnames of servers where the application is deployed. The hostnames of servers are represented as an array.

```ruby
app_to_hostnames[app_name] = hostnames {
    apps[_] = app
    app_name = app.name
    hostnames = [hostname | name = app.servers[_]
                            sites[_].servers[_] = s
                            s.name = name
                            hostname = s.hostname]
}
```

The result:

```ruby
> app_to_hostnames[app] = hostnames
+-----------+------------------------------------------------------+
|    app    |                      hostnames                       |
+-----------+------------------------------------------------------+
| "web"     | ["hydrogen","helium","beryllium","boron","nitrogen"] |
| "mysql"   | ["lithium","carbon"]                                 |
| "mongodb" | ["oxygen"]                                           |
+-----------+------------------------------------------------------+
```

### <a name="object-comprehensions"></a> Object Comprehensions

Object Comprehensions build object values out of sub-queries. Object Comprehensions have the form:

```ruby
{ <key>: <term> | <body> }
```

We can use Object Comprehensions to write the rule from above as a comprehension instead:

```ruby
app_to_hostnames = {app.name: hostnames |
    apps[_] = app
    hostnames = [hostname |
                    name = app.servers[_]
                    sites[_].servers[_] = s
                    s.name = name
                    hostname = s.hostname]
}
```

The result is the same:

```ruby
> app_to_hostnames[app]
+-----------+------------------------------------------------------+
|    app    |                app_to_hostnames[app]                 |
+-----------+------------------------------------------------------+
| "web"     | ["hydrogen","helium","beryllium","boron","nitrogen"] |
| "mysql"   | ["lithium","carbon"]                                 |
| "mongodb" | ["oxygen"]                                           |
+-----------+------------------------------------------------------+
```

Object comprehensions are not allowed to have conflicting entries, similar to rules:

```ruby
> {"foo": y | y = z[_]; z = [1, 2, 3]}
{"foo": y | y = z[_]; z = [1, 2, 3]}: eval_conflict_error: object comprehension produces conflicting outputs
```

### <a name="set-comprehensions"></a> Set Comprehensions

Set Comprehensions build set values out of sub-queries. Set Comprehensions have the form:

```ruby
{ <term> | <body> }
```

For example, to construct a set from an array:
```ruby
> a = [1, 2, 3, 4, 3, 4, 3, 4, 5]
> b = {x | x = a[_]}
> b
[
  1,
  2,
  3,
  4,
  5
]
```

## <a name="rules"></a> Rules

Rules define the content of [Virtual Documents](/how-does-opa-work.md#virtual-documents) in
OPA. When OPA evaluates a rule, we say OPA *generates* the content of the
document that is defined by the rule.

The sample code in this section make use of the data defined in [Examples](#examples).

### <a name="generating-sets"></a> Generating Sets

The following rule defines a set containing the hostnames of all servers:

```ruby
hostnames[name] { sites[_].servers[_].hostname = name }
```

When we query for the content of `hostnames` we see the same data as we would if we queried using the `sites[_].servers[_].hostname` reference directly:

```ruby
> hostnames[name]
+-------------+
|    name     |
+-------------+
| "hydrogen"  |
| "helium"    |
| "lithium"   |
| "beryllium" |
| "boron"     |
| "carbon"    |
| "nitrogen"  |
| "oxygen"    |
+-------------+
```

This example introduces a few important aspects of Rego.

First, the rule defines a set document where the contents are defined by the variable `name`. We know this rule defines a set document because the head only includes a key. All rules have the following form (where key, value, and body are all optional):

```
<name> <key>? <value>? <body>?
```

For a more formal definition of the rule syntax, see the [Language Reference](/language-reference.md#grammar) document.

Second, the `sites[_].servers[_].hostname` fragment selects the `hostname` attribute from all of the objects in the `servers` collection. From reading the fragment in isolation we cannot tell whether the fragment refers to arrays or objects. We only know that it refers to a collections of values.

Third, the `sites[_].servers[_].hostname = name` expression binds the value of the `hostname` attribute to the variable `name`, which is also declared in the head of the rule.

### <a name="generating-objects"></a> Generating Objects

Rules that define objects are very similar to rules that define sets.

```ruby
apps_by_hostname[hostname] = app {
    sites[_].servers[_] = server
    server.hostname = hostname
    apps[i].servers[_] = server.name
    apps[i].name = app
}
```

The rule above defines an object that maps hostnames to app names. The main difference between this rule and one which defines a set is the rule head: in addition to declaring a key, the rule head also declares a value for the document.

The result:

```
> apps_by_hostname["helium"] = app
+-------+
|  app  |
+-------+
| "web" |
+-------+
```

### <a name="incremental-definitions"></a> Incremental Definitions

A rule may be defined multiple times with the same name. When a rule is defined
this way, we refer to the rule definition as *incremental* because each
definition is additive. The document produced by incrementally defined rules is
the union of the documents produced by each individual rule.

For example, we can write a rule that abstracts over our `servers` and
`containers` data as `instances`:

```ruby
instances[instance] {
    sites[_].servers[_] = server
    instance = {"address": server.hostname, "name": server.name}
}

instances[instance] {
    containers[_] = container,
    instance = {"address": container.ipaddress, "name": container.name}
}
```

If the head of the rule is same, we can chain multiple rule bodies together to
obtain the same result:

```ruby
instances[instance] {
    sites[_].servers[_] = server
    instance = {"address": server.hostname, "name": server.name}
} {
    containers[_] = container,
    instance = {"address": container.ipaddress, "name": container.name}
}
```

An incrementally defined rule can be intuitively understood as `<rule-1> OR <rule-2> OR ... OR <rule-N>`.

The result:

```ruby
> instances[x]
+-----------------------------------------------+
|                       x                       |
+-----------------------------------------------+
| {"address":"hydrogen","name":"web-0"}         |
| {"address":"helium","name":"web-1"}           |
| {"address":"lithium","name":"db-0"}           |
| {"address":"beryllium","name":"web-1000"}     |
| {"address":"boron","name":"web-1001"}         |
| {"address":"carbon","name":"db-1000"}         |
| {"address":"nitrogen","name":"web-dev"}       |
| {"address":"oxygen","name":"db-dev"}          |
| {"address":"10.0.0.1","name":"big_stallman"}  |
| {"address":"10.0.0.2","name":"cranky_euclid"} |
+-----------------------------------------------+
```

### <a name="complete-definitions"></a> Complete Definitions

In addition to rules that *partially* define sets and objects, Rego also
supports so-called *complete* definitions of any type of document. Rules provide
a complete definition by omitting the key in the head. Complete definitions are
commonly used for constants:

```ruby
pi = 3.14159
```

> Rego allows authors to omit the body of rules. If the body is omitted, it
> defaults to true.

Documents produced by rules with complete definitions can only have one value at
a time. If evaluation produces multiple values for the same document, an error
will be returned.

For example:

```ruby
# Define user "bob" for test input.
user = "bob"

# Define two sets of users: power users and restricted users. Accidentally
# include "bob" in both.
power_users = {"alice", "bob", "fred"}
restricted_users = {"bob", "kim"}

# Power users get 32GB memory.
max_memory = 32 { power_users[user] }

# Restricted users get 4GB memory.
max_memory = 4 { restricted_users[user] }
```

Error:

```
> max_memory
max_memory: eval_conflict_error: completely defined rules must produce exactly one value
```

OPA returns an error in this case because the rule definitions are in *conflict*. The value produced by max_memory cannot be 32 and 4 **at the same time**.

The documents produced by rules with complete definitions may still be undefined:

```ruby
> unset user
> user = "johnson"  # user is not in either of the sets defined earlier.
> max_memory
undefined
```

In some cases, having an undefined result for a document is not desirable. In those cases, policies can use the [Default Keyword](#default) to provide a fallback value.

### <a name="functions"></a> Functions

Rego supports user-defined functions that can be called with the same semantics as [Built-in Functions](#built-ins). They have access to both the [the data Document](/how-does-opa-work.md#the-data-document) and [the input Document](/how-does-opa-work.md#the-input-document).

For example, the following function will return the result of trimming the spaces from a string and then splitting it by periods.

```ruby
> trim_and_split(s) = x {
|     trim(s, " ", t)
|     split(t, ".", x)
| }
|
> trim_and_split("   foo.bar ", out)
+---------------+
|      out      |
+---------------+
| ["foo","bar"] |
+---------------+
```

Functions may have an arbitrary number of inputs, but exactly one output. Function arguments may be any kind of term. For example, suppose we have the following function:

```
foo([x, {"bar": y}]) = z {
    z = {x: y}
}
```

The following calls would produce the logical mappings given:

| Call                                                  | ``x``      | ``y``                         |
| ----------------------------------------------------- | ---------- | ----------------------------- |
| ``foo(a, z) ``                                        | ``a[0]``   | ``a[1].bar``                  |
| ``foo(["5", {"bar": "hello"}], z)``                   | ``"5"``    | ``"hello"``                   |
| ``foo(["5", {"bar": [1, 2, 3, ["foo", "bar"]]}], z)`` | ``"5"``    | ``[1, 2, 3, ["foo", "bar"]]`` |


If you need multiple outputs, write your functions so that the output is an array, object or set containing your results. If the output term is omitted, it is equivalent to having the output term be the literal `true`. That is, the function declarations below are equivalent:
```
f(x) {
    x = "foo"
}

f(x) = true {
    x = "foo"
}
```

The outputs of user functions have some additional limitations, namely that they must resolve to a single value. If you write a function that has multiple possible bindings for an output variable, you will get a conflict error:

```ruby
> p(x) = y {
|     x[_] = y
| }
|
> p([1, 2, 3], out)
p([1, 2, 3], out): eval_conflict_error: completely defined rules must produce exactly one value
```

It is possible in Rego to define a function more than once, to achieve a conditional selection of which function to execute:

Functions can be defined incrementally.

```ruby
> p(1, x) = y {
|     y = x
| }
|
> p(2, x) = y {
|     y = x*4
| }
|
> p(1, 2, y)
+---+
| y |
+---+
| 2 |
+---+
> p(2, 2, y)
+---+
| y |
+---+
| 8 |
+---+
```

A given function call will execute all functions that match the signature given. If a call matches multiple functions, they must produce the same output, or else a conflict error will occur:

```ruby
> p(1, x) = y {
|     y = x
| }
|
> p(x, 2) = y {
|     y = x*4
| }
|
> p(1, 2, y)
p(1, 2, y): eval_conflict_error: completely defined rules must produce exactly one value
```

On the other hand, if a call matches no functions, then the result is undefined, and the query containing it will become unsatisfied.
```
> p(x, 2) = y {
|     y = x*4
| }
|
> p(5, 2, y)
+----+
| y  |
+----+
| 20 |
+----+
> p(5, 3, y)
false
```

## <a name="negation"></a> Negation

To generate the content of a [Virtual Document](/how-does-opa-work.md#virtual-documents), OPA attempts to bind variables in the body of the rule such that all expressions in the rule evaluate to True.

This generates the correct result when the expressions represent assertions about what states should exist in the data stored in OPA. In some cases, you want to express that certain states *should not* exist in the data stored in OPA. In these cases, negation must be used.

For safety, a variable appearing in a negated expression must also appear in another non-negated equality expression in the rule.

> OPA will reorder expressions to ensure that negated expressions are evaluated after other non-negated expressions with the same variables. OPA will reject rules containing negated expressions that do not meet the safety criteria described above.

The simplest use of negation involves only scalar values or variables and is equivalent to complementing the operator:

```ruby
t {
    greeting = "hello"
    not greeting = "goodbye"
}
```

The result:

```ruby
> t
true
```

Negation is required to check whether some value *does not* exist in a collection. That is, complementing the operator in an expression such as `p[_] = "foo"` yields `p[_] != "foo"`. However, this is not equivalent to `not p["foo"]`.

For example, we can write a rule that defines a document containing names of apps not deployed on the `"prod"` site:

```ruby
prod_servers[name] {
    sites[_] = site
    site.name = "prod"
    site.servers[_].name = name
}

apps_in_prod[name] {
    apps[_] = app
    app.servers[_] = server
    app.name = name
    prod_servers[server]
}

apps_not_in_prod[name] {
    apps[_].name = name
    not apps_in_prod[name]
}
```

The result:

```ruby
> apps_not_in_prod[name]
+-----------+
|   name    |
+-----------+
| "mongodb" |
+-----------+
```

## <a name="modules"></a> Modules

In Rego, policies are defined inside *modules*. Modules consist of:

  * Exactly one [Package](#packages) declaration.
  * Zero or more [Import](#imports) statements.
  * Zero or more [Rule](#rules) definitions.

Modules are typically represented in Unicode text and encoded in UTF-8.

### <a name="comments"></a> Comments

Comments begin with the `#` character and continue until the end of the line.

### <a name="packages"></a> Packages

Packages group the rules defined in one or more modules into a particular namespace. Because rules are namespaced they can be safely shared across projects.

Modules contributing to the same package do not have to be located in the same directory.

The rules defined in a module are automatically exported. That is, they can be queried under OPA’s [Data API](/rest-api.md#data-api) provided the appropriate package is given. For example, given the following module:

```ruby
package opa.examples

pi = 3.14159
```

The `pi` document can be queried via the Data API:

```http
GET https://example.com/v1/data/opa/examples/pi HTTP/1.1
```

### <a name="imports"></a> Imports

Import statements declare dependencies that modules have on documents defined outside the package. By importing a document, the identifiers exported by that document can be referenced within the current module.

All modules contain implicit statements which import the `data` and `input` documents.

Modules use the same syntax to declare dependencies on [Base Documents](../how-does-opa-work#base-documents) and [Virtual Documents](../how-does-opa-work#virtual-documents).

```ruby
package opa.examples

import data.servers

http_servers[server] {
    server = servers[_]
    server.protocols[_] = "http"
}
```

Similarly, modules can declare dependencies on query arguments by specifying an import path that starts with `input`.

```ruby
package opa.examples

import input.user
import input.method

# allow alice to perform any operation.
allow { user = "alice" }

# allow bob to perform read-only operations.
allow {
    user = "bob"
    method = "GET"
}
```

Imports can include an optional `as` keyword to handle namespacing issues:

```ruby
package opa.examples

import data.servers as my_servers

http_servers[server] {
    server = my_servers[_]
    server.protocols[_] = "http"
}
```

## <a name="with-keyword"></a> With Keyword

The `with` keyword allows queries to programmatically specify values nested
under [The input Document](../how-does-opa-work#the-input-document).

For example, given the simple authorization policy in the [Imports](#imports)
section, we can write a query that checks whether a particular request would be
allowed:

```ruby
> import data.opa.examples.allow
> allow with input as {"user": "alice", "method": "POST"}
true
> allow with input as {"user": "bob", "method": "GET"}
true
> not allow with input as {"user": "bob", "method": "DELETE"}
true
```

The `with` keyword acts as a modifier on expressions. A single expression is
allowed to have zero or more `with` modifiers. The `with` keyword has the
following syntax:

```
<expr> with <target-1> as <value-1> [with <target-2> as <value-2> [...]]
```

The `<target>`s must be references to values in the input document (or the input
document itself). The `<value>`s may be Scalar Values, Variables, or Composite
Values that do not contain References or Comprehensions.

## <a name="default-keyword"></a> Default Keyword

The `default` keyword allows policies to define a default value for documents
produced by rules with [Complete Definitions](#complete-definitions). The
default value is used when all of the rules sharing the same name are undefined.

For example:

```ruby
default allow = false

allow {
    input.user = "bob"
    input.method = "GET"
}

allow {
    input.user = "alice"
}
```

When the `allow` document is queried, the return value will be either `true` or `false`.

```ruby
> allow with input.user as "bob" with input.method as "POST"
false
```

Without the default definition, the `allow` document would simply be undefined for the same input.

When the `default` keyword is used, the rule syntax is restricted to:

```
default <name> = <term>
```

The term may be any scalar, composite, or comprehension value but it may not be
a variable or reference. If the value is a composite then it may not contain
variables or references.

## <a name="else-keyword"></a> Else Keyword

The ``else``  keyword is a basic control flow construct that gives you control
over rule evaluation order.

Rules grouped together with the ``else`` keyword are evaluated until a match is
found. Once a match is found, rule evaluation does not proceed to rules further
in the chain.

The ``else`` keyword is useful if you are porting policies into Rego from an
order-sensitive system like IPTables.

```
# Service queries "authorize" and intreprets result ("allow" or "deny")
authorize = "allow" {
    input.user = "superuser"
}

# Check if caller is from outside network.
else = "deny" {
    input.path[0] = "admin"
    input.source_network = "external"
}

# Check if caller is from inside network.
else = "allow" {
    input.path[0] = "admin"
    input.source_network = "internal"
} # ... more rules
```

## <a name="operators"></a> Operators

### <a name="equality"></a> Equality

The equality operator (`=`) is used to define expressions that assert that two values are the same. If the expression is defined in terms of one or more variables then the expression will evaluate to true if one of the variables is unbound. If the neither operand is an unbound variable, the expression is evaluated by comparing the *values* referenced by the operands.

OPA attempts to *bind* variables to values when it encounters unbound variables in equality expressions. Binding a variable affects subsequent evaluation of expressions such that the variable will be treated as a constant (with the bound value) instead of a variable.

### <a name="inequality"></a> Inequality

The following inequality operators are supported:

```ruby
a  !=  b  #  `a` is not equal to `b`.
a  <   b  #  `a` is less than `b`.
a  <=  b  #  `a` is less than or equal to `b`.
a  >   b  #  `a` is greater than `b`.
a  >=  b  #  `a` is greater than or equal to `b`.
```

Unlike the equality operator, these operators do not bind variables contained in the expression. As a result, if either operand is a variable, the variable must appear in another expression in the same rule that would cause the variable to be bound, i.e., an equality expression or the target position of a built-in function.

## <a name="built-in-functions"></a> Built-in Functions

In some cases, rules must perform simple arithmetic, aggregation, and so on.
Rego provides a number of built-in functions (or “built-ins”) for performing
these tasks.

Built-ins can be easily recognized by their syntax. All built-ins have the
following form:

```
<name>(<arg-1>, <arg-2>, ..., <arg-n>)
```

Built-ins usually take one or more input values and produce at least one output
value. Unless stated otherwise, all built-ins accept values or variables as
output arguments.

Built-ins can include "." characters in the name. This allows them to be
namespaced. If you are adding custom built-ins to OPA, consider namespacing
them to avoid naming conflicts, e.g., `org.example.special_func`.

See the [Language Reference](/language-reference.md#built-in-functions) document for
details on each built-in function.

## <a name="example-data"></a> Example Data

The rules below define the content of documents describing a simplistic deployment environment. These documents are referenced in other sections above.

```ruby
sites = [
    {
        "region": "east",
        "name": "prod",
        "servers": [
            {
                "name": "web-0",
                "hostname": "hydrogen"
            },
            {
                "name": "web-1",
                "hostname": "helium"
            },
            {
                "name": "db-0",
                "hostname": "lithium"
            }
        ]
    },
    {
        "region": "west",
        "name": "smoke",
        "servers": [
            {
                "name": "web-1000",
                "hostname": "beryllium"
            },
            {
                "name": "web-1001",
                "hostname": "boron"
            },
            {
                "name": "db-1000",
                "hostname": "carbon"
            }
        ]
    },
    {
        "region": "west",
        "name": "dev",
        "servers": [
            {
                "name": "web-dev",
                "hostname": "nitrogen"
            },
            {
                "name": "db-dev",
                "hostname": "oxygen"
            }
        ]
    }
]

apps = [
    {
        "name": "web",
        "servers": ["web-0", "web-1", "web-1000", "web-1001", "web-dev"]
    },
    {
        "name": "mysql",
        "servers": ["db-0", "db-1000"]
    },
    {
        "name": "mongodb",
        "servers": ["db-dev"]
    }
]

containers = [
    {
        "image": "redis",
        "ipaddress": "10.0.0.1",
        "name": "big_stallman"
    },
    {
        "image": "nginx",
        "ipaddress": "10.0.0.2",
        "name": "cranky_euclid"
    }
]
```
