L the languagewlG github

Your data isalready a graph.Query it that way.

Owl is a database for objects that point at each other.
You follow the references. You never write a join.

orders.customer.name

H to hoot

The language · OQL

Learn the verbs once.
Use them on everything.

Seven short chapters, from describing your data to questions that are hard in SQL. Every one runs on the same six orders, and every answer shown came from a real Owl server.

Say what your data looks like.

schema customers {
  id: String,
  name: String,
  country: String
}

schema orders {
  id: String,
  status: String,
  total: Float,
  customer: Ref(customers),
  items: List({
    product: Ref(products),
    qty: Integer
  })
}

A schema names a collection and the type of each field.

customersidnamecountry.ordersderivedordersidstatustotalcustomeritemsproduct qtya list, per order.customer.orders

Two forms

Chain it or block it.
Owl reads one query.

Every query can be written as a chain of steps or as a block. They are the same language and give the same answer. Pick the one that reads better.

The same query, piece by piece

Chain
orders
  .where { .status == "paid" }
  .sort { .total.desc }
  .limit(3)
  .select { id, who: .customer.name, total }
One query
Block
orders {
  where { .status == "paid" }
  sort { .total.desc }
  limit 3
  select { id, who: .customer.name, total }
}

Both start from a collection. A chain hangs steps off it with dots. A block opens a pair of braces and puts the steps inside.

Owl answers, either way
{ id: "o1", who: "Ada", total: 125.0 }
{ id: "o6", who: "Ada", total: 97.0 }
{ id: "o2", who: "Bola", total: 85.0 }

What a block adds: names

A block can name something once and use it wherever it is needed. That is the one thing it has that a chain does not.

Each customer's paid orders, counted. So far the chain is no longer than the block.

Chainpaid orders written once
customers
  .sort { .id.asc }
  .select {
    name,
    orders: .orders.where { .status == "paid" }.count()
  }
Blockpaid orders written once
customers {
  paid = .orders.where { .status == "paid" }

  sort { .id.asc }
  select { name, orders: paid.count() }
}
customerpaidordersspentAdao1125o6972222over 80Bolao285185over 80Cheno452152not over 80
Owl answers, either way
{ name: "Ada", orders: 2 }
{ name: "Bola", orders: 1 }
{ name: "Chen", orders: 1 }

The rules of a block

01

It reads top to bottom

Names first, then the steps in the order you want them, then the answer.

customers {
  paid = .orders.where { .status == "paid" }
  where { paid.count() > 0 }
  select { name }
}
02

It ends with the answer

A block finishes with select, or with a closing step such as count(). Nothing comes after it.

customers {
  select { name, country }
  where { .country == "NG" }
}

Owl says select must be the final entry in a scoped query block

03

One name, one meaning

A name cannot be given twice, and it cannot reuse the name of the collection the block is about.

customers {
  paid = .orders.where { .status == "paid" }
  paid = .orders
  select { name }
}

Owl says Scoped binding 'paid' is already defined

04

Names stay inside

A block is a whole query. Its names do not exist outside it, and nothing can be chained on after it closes.

customers {
  paid = .orders.where { .status == "paid" }
  select { name }
}.where { paid.count() > 0 }

Owl says Expected end of query, found '.'

05

The collection's name means this row

Inside a nested query, . is the nested row. The outer collection's name still reaches the row the block is on.

customers {
  sort { .id.asc }
  select {
    name,
    n: orders
      .where { .customer == customers.id }
      .count()
  }
}

Which to reach for

Chain

For a short run of steps, and for anything that carries on after select, such as sorting by a field the select just worked out.

Block

When the query uses the same fact more than once, or when naming the parts makes a long query easier to read.

Functions

Teach Owl
your own words.

A function gives a name to a measure, a rule, a test or a path. You write it in OQL, Owl keeps it in the database, and from then on every query can use the word.

A row goes in. A number comes out.

Define it once
fn spent(c: customers) {
  c.orders
    .where { .status == "paid" }
    .sum(.total)
}
Use it
customers.sort { .id.asc }.select {
  name,
  spent: spent(*)
}
AdaBolaChen2228552spent()goes incomes out
Owl answers
{ name: "Ada", spent: 222.0 }
{ name: "Bola", spent: 85.0 }
{ name: "Chen", spent: 52.0 }

* hands the function the whole current row. Inside, c.orders walks the reference back, the same as anywhere else in OQL.

Good forlifetime spendopen balancedays since the last order

One definition, every caller

A function lives in the database, not in each program that talks to it. Change the rule once and every caller gets the new answer.

In the database
fn tier(spent) {
  if spent >= 200 then "gold"
  else if spent >= 80 then "silver"
  else "bronze"
}

A dashboard

Ada gold

Bola silver

Chen bronze

The checkout service

{ "who": "Ada",
  "tier": "gold" }
{ "who": "Bola",
  "tier": "silver" }
{ "who": "Chen",
  "tier": "bronze" }

The monthly report

gold1

silver1

bronze1

Move the slider. This page works the rule out itself to show the effect. On a real server, defining tier again with 250 turned Ada from gold to silver in every query that used it.

Kept with your data. A definition is written to the database like any other row.

Still there tomorrow. It survives a restart.

Replaced by saying it again. The latest definition is the one Owl uses.

Undone with its transaction. Roll the transaction back and the old definition returns.

What comes in the box

The last row is written in OQL, the same way yours are. Define one of the same name and yours takes its place.

Text

trimupperlowerlengthsubstringconcatreplacesplitstarts_withends_withcontainsmatchespad_leftpad_right

Numbers

absroundfloorceilsqrtpowminmaxloglnexprandom

Dates

nowtodaydays_agohours_agoformat_dateparse_dateyearmonthdayweekdayadd_daysdiff_daysdays_untildays_since

Values

coalesceif_nullto_stringto_intto_floatto_booltype_of

Written in OQL itself

variancestddevvariance_popstddev_popmode

Writing

Change data in
the same language.

Writes start from a collection, like reads do, and use the same where. The schema holds the rules, and Owl refuses any write that would break one.

Add a row by writing its shape.

You write
customers.insert {
  id: "chen",
  name: "Chen",
  email: "chen@shop.test",
  address: { city: "Singapore" }
}

customers

idnameemail
adaAdaada@shop.test
bolaBolabola@shop.test
Owl answers with the row it touched
{ id: "chen", name: "Chen", email: "chen@shop.test",
  address: { city: "Singapore" } }

Give insert a list in square brackets and it adds them all, or none: one bad row in the list and nothing is added.

Rules that live in the schema

You say once what must always be true. Owl checks it on every write, whichever program is asking.

The schema
schema customers {
  id: String,
  name: String,
  email: String unique
}

schema products {
  id: String,
  price: Float,
  stock: Integer,
  check(.price >= 0 && .stock >= 0)
}

schema orders {
  id: String,
  customer: Ref(customers),
  qty: Integer
}

schema payments {
  id: String,
  order: Ref(orders) on delete cascade
}

Try to break it

You write
customers.insert {
  id: "eve", name: "Eve",
  email: "ada@shop.test",
  address: { city: "Accra" }
}
Refused

Owl says 'customers' document 'eve' has email "ada@shop.test", which must be unique, and another document already has it

One statement is all or nothing

The test and the change happen together, so two buyers cannot both take the last kettle. Most updates need nothing more than this.

One statement
products
  .where { .id == "kettle" && .stock > 0 }
  .update { stock -= 1 }
2kettles in stock

    A transaction makes several statements one

    When changes only make sense together, put them in a transaction block. If any one fails, none of them happened.

    Two statements that belong together
    transaction {
      orders.insert {
        id: "o4", customer: "ada",
        product: "kettle", qty: 2, status: "paid"
      }
      products
        .where { .id == "kettle" }
        .update { stock -= 2 }
    }

    orders

    o1o2o3o4

    kettle stock

    1the order wants 2

    Only one kettle is left, and Ada wants two. Run it both ways.

    The engine

    Rust, all
    the way down.

    There is no other database underneath. Owl's own engine stores the data, and it knows your schema and your references, so it can use both.

    01

    References that never break

    Every object has a 64-bit identity that says nothing about where it is stored. Owl can move the data and every reference still holds.

    collection16object32generation16
    02

    Records shaped by your schema

    Field names are stored once, not in every record. Ask for two fields and Owl decodes two fields.

    03

    Writes that survive a crash

    Every commit is checksummed and synced to disk before any reader sees it. After a crash, Owl loads its last checkpoint and replays the rest.

    04

    Indexes that know the graph

    Every reference gets an index for the way back. You can add ordered, unique, composite and vector indexes.

    Evidence

    Right first.
    Then fast.

    Two suites give Owl and SQLite the same data, the same indexes and the same durability, then require the same rows back. Only then is anything timed. One suite is an ordinary shop. The other is built to be hard.

    The shop suite has sixteen queries. Its check fails unless both engines return the same rows for every one.

    Read the suites

    Run it

    Three commands
    to a first answer.

    # 1. Start a server (needs only a Rust toolchain)
    cargo run --release -p owl-server -- --data shop.owl
    
    # 2. Declare two collections and add a row to each
    curl 127.0.0.1:7878/v1/script --json '{"source": "schema customers { id: String, name: String }\nschema orders { id: String, customer: Ref(customers), total: Float }\ncustomers.insert { id: \"c1\", name: \"Ada\" }\norders.insert { id: \"o1\", customer: \"c1\", total: 12.5 }"}'
    
    # 3. Follow the reference from order to customer
    curl 127.0.0.1:7878/v1/query --json '{"query": "orders.select { id, who: .customer.name }"}'
    
    {"rows":[{"id":"o1","who":"Ada"}]}

    Join in

    Owl is young.
    Help it grow.

    Owl is open source under the MIT license, and it is early. If you like where it is going, here are three ways to help, from ten seconds to a weekend.

    Ten seconds

    Give it a star

    A star costs nothing, and it is how other people come across a project this new.

    Star Owl on GitHub
    Ten minutes

    Try it and say what broke

    Run the three commands above against data shaped like yours. A query Owl gets wrong, or cannot say, is the most useful report there is.

    Open an issue
    A weekend

    Help build it

    The priority right now is getting storage right. Good places to start:

    crash testsformat fuzzingthe record codeckey encodingindex testsrepeatable benchmarks

    How to contribute