OPA Rego — functions vs virtual documents and when to use each

Contents

  1. 1. Functions
  2. 2. Virtual documents
  3. 3. Pick one

Rego gives you two ways to package logic: functions and virtual documents. They overlap on paper; in practice the choice comes down to whether you need a relation you can iterate.

We’ll use a file list in input and ask: which paths look like config files?

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// input.json
// posix — normal Unix paths
// traditional-mac — legacy Mac path syntax
{
"files": [
{
"type": "posix",
"path": "/Users/newbmiao/Documents/1.yaml"
},
{
"type": "posix",
"path": "/Users/newbmiao/Documents/2.yaml"
},
{
"type": "traditional-mac",
"path": "Macintosh HD:Users:newbmiao:Documents:3.yml"
},
{
"type": "traditional-mac",
"path": "Macintosh HD:Users:newbmiao:Documents:3.json"
}
]
}

Functions

Rego allows multiple rules with the same name — overload by arity and by how arguments unify. Think lightweight pattern matching, not Java generics.

Properties:

  • Default return is true/false (undefined → false)
  • Or assign with name(args) = value { ... }
  • Same name only if arity differs (or inputs unify differently)
  • Same inputs must always yield the same outputs

Check file extensions — three heads, OR semantics:

1
2
3
4
5
6
7
8
9
10
11
is_config_file(str) {
contains(str, ".yaml")
}

is_config_file(str) {
contains(str, ".yml")
}

is_config_file(str) {
contains(str, ".json")
}

Or chain with else:

1
2
3
4
5
6
7
8
9
10
11
is_config_file2(str) {
contains(str, ".yaml")
}

else {
contains(str, ".yml")
}

else {
contains(str, ".json")
}

Value-returning overload — extract a filename per path style:

1
2
3
4
5
6
7
8
9
10
11
12
13
getFileName(type, str) = x {
type = "posix"
str = trim(str)
tmp := split(str, "/")
x := tmp[minus(count(tmp), 1)]
}

getFileName(type, str) = x {
type = "traditional-mac"
str = trim(str)
tmp := split(str, ":")
x := tmp[minus(count(tmp), 1)]
}

Looks like duplicate signatures; the type = "posix" / type = "traditional-mac" lines discriminate inputs — similar to getFileName("posix", str) vs getFileName("traditional-mac", str).

Drop those guards and you’ll hit:

eval_conflict_error: functions must not produce multiple outputs for same inputs

Wire it together:

1
2
3
4
5
6
7
import input.files

is_config {
file := files[_]
x := getFileName(file.type, file.path)
is_config_file(x)
}

Builtins: policy reference

Virtual documents

A virtual document is a finite relation you can query and enumerate — getFileNames[x] defines the set of names.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import input.files

getFileNames[x] {
file := files[_]
file.type = "posix"
file.path = trim(file.path)
tmp := split(file.path, "/")
x := tmp[minus(count(tmp), 1)]
}

getFileNames[x] {
file := files[_]
file.type = "traditional-mac"
file.path = trim(file.path)
tmp := split(file.path, ":")
x := tmp[minus(count(tmp), 1)]
}

getFileNames[x] { ... } is shorthand for getFileNames[x] = x { ... } — each successful x becomes a member.

Eval:

1
2
3
4
5
6
7
8
9
10
cd syntax
opa eval -f values -i input.json -d . "data.example_virtual_doc.getFileNames"
[
[
"1.yaml",
"2.yaml",
"3.yml",
"3.json"
]
]

Iterate and filter:

1
2
3
4
5
6
import data.example_func.is_config_file
import input.files

is_config {
is_config_file(getFileNames[_])
}

getFileNames[_] walks the set; each binding feeds is_config_file.

Pick one

Ask:

  • Do you need to enumerate results?
  • Is the output finite for a given input?

If either is yes, lean virtual document. Pure transforms on known arguments → function.

Next: comprehensions for the compact aggregation syntax.

Code: NewbMiao/opa-koans/syntax

Questions? Leave a comment below or email: newbvirgil@gmail.com