Chapter 1

What a Query Is

By the end of this chapter you will be able to

define a query as Ocalt counts it, and recognise every way one is spent;
explain the daily allowance, when it resets, and what each plan provides;
describe how credits take over once the allowance is spent;
test a script without spending anything;
predict what happens when nothing is left to spend.

Before you start

An Ocalt account.
Having run at least one OcaltQL script, in the Console or through the API.

The big picture

Ocalt meters exactly one thing: queries. Storage aside, nothing else is rationed by plan. There is no ceiling on machines, subdomains, domains, databases or files. Every plan, Free included, can use every verb.

So understanding queries is understanding the whole of what Ocalt charges for. This chapter defines one precisely. Chapter 2 shows what makes them add up, and how to spend fewer.

Key terms

Query: One execution of a script, however it was started.
Daily allowance: The queries a plan includes each day.
Credit: A purchased query, used once the daily allowance is spent. Credits never expire.
Dry run: Checking that a script parses without running it. It costs nothing.
429: The answer when no allowance and no credits remain.

1.1 One execution, one query

A query is one execution of a script. It does not matter how long the script is, how many statements it chains, or what they do.

Worked Example 1.1

One query, however much it does

Task. Write a small report to a file, read it back, and emit it.

The script.

FILE WRITE "Report for today" TO "/root/reports/today.txt"
AFTER FILE READ "/root/reports/today.txt" SET ?report
AFTER EMIT ?report

What comes back.

Report for today

Line by line.

FILE WRITE ... AFTER FILE READ ... AFTER EMIT	Three statements chained in one script.
Cost	One query. The script ran once.

The rule is written into the pricing itself: apart from the few operations with their own charge (below), what a script does inside itself is not counted. One execution that writes a thousand files, drives a browser, solves a simulation and commands ten machines costs one query, exactly like one that emits hello.

Think about it

A script writes 500 files in a loop, then emails a summary. How many queries?

Show the answer

One. The loop and the email are both inside the one execution.

1.2 Every way a query is spent

Since a query is an execution, the question is always what started an execution? Each of these is one:

A call to POST /api	Your code, the Console, or an app sending a script.
A page view of a Site Mode .oql file	Each visitor who loads a page that runs OcaltQL. Static files such as images, CSS and HTML are free.
A SCHEDULE or CRON job firing	Each time it runs, not when it is created.
A WATCH poll	Each check, and separately its trigger when it fires.
Opening a TUNNEL or a SERVE	And every visit to the URL it produced.
Each connection to an audio or video bridge	Each participant joining.

Commanding a machine, reading and writing files, using a database and sending mail all happen inside a script, so they are part of that script's one query.

Operations with their own charge

A few operations create something lasting, or open something others can reach, and are charged on top of the query of the run that performs them:

Operation	Queries
Each application package generated (APPLICATE)	64
Each mailbox created (NEW EMAIL ACCOUNT)	10
Each subdomain added (SUBDOMAIN ADD)	10
Each custom domain added (DOMAIN)	10
Each network mapping created (NETWORK MAP)	10
Each WebAssembly service published, or streaming link made	1

Such a charge is made in one step, before the operation runs: from the day's allowance first, then from credits. If the two cannot cover it, nothing is spent and the statement fails before doing anything. The run's own query is separate, so a script that only creates a mailbox costs 11.

1.3 The daily allowance

Each plan includes a number of queries per day:

Plan	Price	Queries a day	Mounted storage
Free	$0/mo	100	none
Starter	$12/mo	1,000	8GB
Pro	$49/mo	10,000	64GB
Enterprise	$199/mo	100,000	256GB
Syndicate Starter	$499/mo	1,000,000	512GB
Syndicate Pro	$999/mo	10,000,000	1TB
Syndicate Max	$2,999/mo	100,000,000	8TB
Syndicate Max B	$4,999/mo	1,000,000,000	16TB

The day is counted in UTC: the allowance resets at midnight UTC, whatever your time zone. In South Africa (UTC+2) that is 02:00 local time.

Think about it

You are on Starter in Johannesburg and have spent all 1,000 queries by 23:00 local time. When does your allowance return?

Show the answer

At 02:00 local time, which is midnight UTC. That is three hours later, not one.

1.4 Credits

A one-time $5 purchase adds 1,000 queries as credits, on any plan, as often as needed, from the account dashboard. Credits have three properties:

Used last	Credits are drawn on only after the day's allowance is spent. A day that stays within the allowance leaves them untouched.
Never expire	Unused credits stay on the account indefinitely.
One at a time	Each query beyond the allowance spends exactly one credit. The balance can never go below zero, even when many scripts run at once.

1.5 When nothing is left

With the allowance spent and no credits remaining, a new execution is refused with 429 Too Many Requests and the message Query Limit Reached. It is the only usage-based refusal on the platform.

Worked Example 1.2

What a refused request looks like

Task. Send a script from outside Ocalt once nothing is left to spend.

The request.

curl -s -X POST https://ql.ocalt.com/api 
  --data-urlencode "identity=$OCALT_IDENTITY" 
  --data-urlencode "password=$OCALT_KEY" 
  --data-urlencode 'q=EMIT "hello"'

What comes back.

HTTP 429
Query Limit Reached

Line by line.

429	The request was understood, and refused only because nothing is left to spend.
What to do	Wait for midnight UTC, or add credits from the account dashboard.

1.6 Testing for free

Sending a script with dry_run=1 asks OcaltQL only whether it parses. Nothing runs, and nothing is spent. A script that fails to parse costs nothing either: a script the runtime refused to accept is not a query it ran.

Worked Example 1.3

Checking a script before running it

Task. Check that a script is well formed without spending a query.

The request.

curl -s -X POST https://ql.ocalt.com/api 
  --data-urlencode "identity=$OCALT_IDENTITY" 
  --data-urlencode "password=$OCALT_KEY" 
  -d dry_run=1 
  --data-urlencode 'q=FILE READ "/root/notes.txt" SET ?n AFTER EMIT ?n'

What comes back.

Parses cleanly. Nothing was run.

Line by line.

dry_run=1	Parse only. The script is read and checked, never executed.
Cost	Nothing, which makes it the right way to check a long script while writing it.

1.7 Practice

Practice 1.4 · one gap

Fill in what a dry run costs.

A dry run costs ____ queries.

Show the answer

Nothing: 0.

Practice 1.5 · two gaps

Complete the rule.

Credits are used only after the ______ ________ is spent.

Show the answer

The daily allowance.

Practice 1.6 · no scaffold

A script chains six statements, commands two machines and sends an email. How many queries does one run cost?

Show the answer

One. Everything it does happens inside the one execution.

1.8 Common mistakes

Mistake: counting statements

A script is one query however many statements it chains. Splitting work into several scripts costs more, not less.

Mistake: expecting the allowance at local midnight

The day is UTC. In UTC+2 it resets at 02:00 local time.

Mistake: buying credits for a quiet day

Credits are only used once the allowance is spent. On a day that stays within it, they are untouched, and they do not expire.

1.9 Check your understanding

1. What is one query?

One execution of a script, however it was started.

2. Does a static image on a site cost a query?

No. Only page views of .oql files do.

3. When are credits used?

Only once the day's allowance is spent. They never expire.

4. What does a failed parse cost?

Nothing. Only scripts that run are queries.

5. A script creates one mailbox and nothing else. What does it cost?

Eleven queries: one for the run and ten for the mailbox.

Summary

A query is one execution of a script. Everything inside it is part of that one query.
Queries are spent by API calls, Site Mode page views, CRON and SCHEDULE runs, WATCH polls and triggers, TUNNEL and SERVE openings and visits, and bridge connections.
A few operations carry their own charge: 64 for an application package, 10 each for a mailbox, a subdomain, a custom domain or a network mapping. They are charged whole before running, or not at all.
The daily allowance depends on the plan and resets at midnight UTC.
Credits ($5 for 1,000) are used after the allowance, one per query, and never expire.
With neither left, the answer is 429 Query Limit Reached. Dry runs and failed parses cost nothing.

← Contents Chapter 2: What Adds Up, and Spending Less →