Skip to main content

Functions Architecture

Technical Overview

This document provides an in-depth technical overview of ekoDB's Functions system. For practical usage examples, see Advanced Operations - Functions.

Overview​

ekoDB's Functions system is a powerful server-side execution engine that enables you to define, version, and execute complex business logic as composable operations. Unlike traditional stored procedures, ekoDB Functions are JSON-based, parameterized, and designed for modern application architectures.

Key Concepts​

Function: A stored procedure containing one or more operations (Query, Insert, Update, Delete, Chat, Embed, etc.)

Operation: A single database action within a Function (referred to in the functions array)

Composability: Functions can call other Functions using CallFunction for reuse. Cross-function calls are bounded by max_function_call_depth, which defaults to 16 and can be configured from 2 to 256.

Why Functions?​

Traditional Approach Problems​

// ❌ Business logic scattered across application code
async function getEnrichedUserData(userId: string) {
// Query user
const user = await db.findOne("users", { id: userId });

// Query orders
const orders = await db.find("orders", { user_id: userId, status: "active" });

// Generate AI summary
const summary = await openai.complete(`Summarize: ${JSON.stringify(orders)}`);

// Update user with summary
await db.update("users", userId, { ai_summary: summary });

return { user, orders, summary };
}

Issues:

  • Multiple network round-trips
  • Logic duplicated in every client
  • Hard to version and maintain
  • No transaction guarantees

ekoDB Functions Approach​

// ✅ Define once, call from anywhere
{
"label": "get_user_orders",
"name": "Get User Orders with Count",
"parameters": {
"user_id": { "required": true },
"status": { "required": false, "default": "active" }
},
"functions": [
{
"type": "Query",
"collection": "orders",
"filter": {
"type": "Logical",
"content": {
"operator": "And",
"expressions": [
{
"type": "Condition",
"content": {
"field": "user_id",
"operator": "Eq",
"value": "{{user_id}}"
}
},
{
"type": "Condition",
"content": {
"field": "status",
"operator": "Eq",
"value": "{{status}}"
}
}
]
}
},
"limit": 50
},
{
"type": "Count",
"output_field": "total_orders"
},
{
"type": "Project",
"fields": ["id", "amount", "status", "total_orders"],
"exclude": false
}
]
}

Benefits:

  • ✅ Single network call
  • ✅ Defined once, used everywhere
  • ✅ Version controlled
  • ✅ Server-side execution
  • ✅ Automatic required and unknown parameter validation

Architecture​

Operation Types​

ekoDB Functions support these step types (the type field of each step). This is the complete catalog.

Query & Read​

  • FindAll - Retrieve all records in a collection
  • Query - Filter, sort, and paginate (filter/sort/limit/skip are inline on this step)
  • FindById - Get one record by ID
  • FindOne - Find one record by key/value
  • TextSearch - Full-text search
  • VectorSearch - Semantic similarity (vector) search
  • HybridSearch - Combined text + vector search

Write (CRUD)​

  • Insert - Insert one record
  • BatchInsert - Insert many records
  • Update - Update records matching a filter
  • UpdateById - Update one record by ID
  • FindOneAndUpdate - Atomic find-and-update
  • UpdateWithAction - Atomic field action (increment, push, append, pop, etc.)
  • Upsert - Find by lookup key, then update the match or insert a new record. The lookup and the write are two steps with no lock between them: when two callers can upsert the same key at once, take LockAcquire on that key first and branch on lock.acquired: the lock does not wait, so a caller that loses gets acquired: false and should return busy and retry; the winner runs the Upsert, then LockRelease
  • Delete - Delete records matching a filter
  • DeleteById - Delete one record by ID
  • BatchDelete - Delete many records by ID

In-pipeline record edits​

  • SetField - Set a literal value on the working record
  • Increment - Atomic counter add on a stored record
  • Push - Atomic array append on a stored record
  • CurrentDatetime - Stamp the current UTC time onto the working record

Aggregation & shaping​

  • Group - Group and aggregate (11 operations: Count, Sum, Average, Min, Max, First, Last, Push, AddToSet, StandardDeviation, ApproxDistinct)
  • AddFields - Add computed/derived fields (arithmetic, string, and conditional expressions)
  • Project - Select or exclude fields
  • Count - Add a record-count field

Control flow​

  • If - Branch on a FunctionCondition
  • ForEach - Iterate over the working records, running sub-steps per record
  • Parallel - Run sub-steps concurrently and merge their results
  • TryCatch - Run steps; on error, run the catch steps (error bound to output_error_field)
  • Sleep - Pause (e.g. for rate limits or retry backoff)
  • Return - Build the final response object (optionally setting status_code for the HTTP status)
  • Validate - Validate a named data field against a JSON Schema, with optional on_error stages
  • CallFunction - Call another saved function by label (composition)

Transactions​

  • CreateSavepoint / RollbackToSavepoint / ReleaseSavepoint - Nested-transaction savepoints for partial rollback

A saved function with transaction_config.enabled = true runs supported write stages (Insert, Update, and Delete) as one buffered, isolated unit. Filtered updates and deletes see earlier staged writes (read-your-writes), and savepoints rewind the buffer. Unsupported stages fail instead of silently running outside the transaction. SWR is the exception: its collection write participates, but its outbound HTTP request and KV cache side effects cannot be rolled back. See Transactions for isolation semantics and design transactional functions with that boundary in mind.

AI​

  • Chat - LLM chat completion
  • Embed - Generate embeddings for a field

Auth & crypto (build login/signup without external services)​

  • BcryptHash / BcryptVerify - Password hashing and verification
  • JwtSign / JwtVerify - Issue and verify JWTs (HMAC, RSA, ECDSA, EdDSA — see JWT Signing and Verification)
  • HmacSign / HmacVerify - HMAC sign and timing-safe verify
  • AesEncrypt / AesDecrypt - AES-GCM encrypt/decrypt
  • TotpGenerate / TotpVerify - TOTP MFA codes
  • RandomToken - CSPRNG random token
  • UuidGenerate - Generate a UUID
  • Base64Encode / Base64Decode - Base64
  • HexEncode / HexDecode - Hex
  • Slugify - URL-safe slug

Key-value store​

  • KvGet / KvSet / KvDelete / KvExists / KvQuery - KV cache operations. KvQuery.pattern is a regular expression, not a literal prefix.

Caching & concurrency​

  • SWR - Stale-while-revalidate cached pipeline (cache check → run → cache set)
  • IdempotencyClaim - Claim an idempotency key (once-only execution)
  • RateLimit - Fixed-window rate limit
  • LockAcquire / LockRelease - Distributed lock

External integrations​

  • HttpRequest - Call an external HTTP API (Stripe, SendGrid, etc.)
  • EmailSend - Send an email

Parameter System​

Functions support dynamic parameterization using {{parameter_name}} syntax. Each parameter definition supports required, default, and description; definitions do not declare a type or enum, and ekoDB does not perform parameter type or enum validation. For example:

{
"parameters": {
"user_id": {
"required": true,
"description": "User identifier"
},
"limit": {
"required": false,
"default": 10,
"description": "Result limit"
},
"status": {
"required": false,
"default": "active",
"description": "Order status"
}
},
"functions": [
{
"type": "Query",
"collection": "users",
"filter": {
"type": "Logical",
"content": {
"operator": "And",
"expressions": [
{
"type": "Condition",
"content": {
"field": "id",
"operator": "Eq",
"value": "{{user_id}}"
}
},
{
"type": "Condition",
"content": {
"field": "status",
"operator": "Eq",
"value": "{{status}}"
}
}
]
}
},
"limit": "{{limit}}"
}
]
}

Parameter Resolution:

  1. User provides values when calling Function
  2. ekoDB applies defaults, then rejects missing required parameters and unknown parameter names (ekoDB-supplied system parameters are exempt)
  3. Parameters are substituted before execution
  4. Results can reference previous Function outputs

Placeholders that are not filled. A {{name}} that no supplied parameter, default or earlier step fills is left in place as the literal text {{name}}; it does not become null. A filter comparing against it matches nothing, and a record field set from it stores the text. Give every optional parameter a default, pass null explicitly when you mean null, or leave the field out of the step.

Where a placeholder can stand in for a number. A Query step's limit and skip accept "{{param}}", as in the example above. The limit of TextSearch, VectorSearch and HybridSearch must be a literal number: a placeholder there is refused when the function is saved. TextSearch and HybridSearch return 10 results when limit is omitted.

Result Chaining​

Operations execute sequentially, with results flowing from one to the next:

{
"functions": [
{
"type": "Query",
"collection": "products",
"filter": {
"type": "Condition",
"content": {
"field": "category",
"operator": "Eq",
"value": "{{category}}"
}
}
},
{
"type": "Count",
"output_field": "product_count"
},
{
"type": "Project",
"fields": ["name", "price", "product_count"],
"exclude": false
}
]
}

How Results Flow:

  • Query operation returns records
  • Count adds a count field to those records
  • Project selects only specified fields
  • Each operation works with the current set of records

Computed Fields (AddFields)​

AddFields adds fields computed per working record. Each entry is { "field_name": ..., "expression": ... }, and an expression is an object with a type and a value:

Expression typevalueResult
LiteralA constant (" ", 5, true, ...)The constant
FieldReferenceA field name or path ("price", "address.city")That field's value; a missing field fails the step
Arithmetic{ "operation": ..., "operands": [<expression>, ...] }Add, Subtract, Multiply, Divide, Modulo, Power take two operands; Sqrt and Abs take one. Operands must be Integer or Float; the result is a Float
StringOperation{ "operation": ..., "operands": [<expression>, ...] }Concat (any number of operands), ToUpper, ToLower, Trim, Length (one operand; Length returns an Integer), Substring (string, start, length), Split (string, delimiter)
Conditional{ "condition": <query expression>, "if_true": <expression>, "if_false": <expression> }if_true when the record matches the filter condition, otherwise if_false
{
"type": "AddFields",
"fields": [
{
"field_name": "total",
"expression": {
"type": "Arithmetic",
"value": {
"operation": "Multiply",
"operands": [
{ "type": "FieldReference", "value": "price" },
{ "type": "FieldReference", "value": "quantity" }
]
}
}
},
{
"field_name": "full_name",
"expression": {
"type": "StringOperation",
"value": {
"operation": "Concat",
"operands": [
{ "type": "FieldReference", "value": "first" },
{ "type": "Literal", "value": " " },
{ "type": "FieldReference", "value": "last" }
]
}
}
},
{
"field_name": "premium",
"expression": {
"type": "Conditional",
"value": {
"condition": {
"type": "Condition",
"content": { "field": "price", "operator": "Gt", "value": 5 }
},
"if_true": { "type": "Literal", "value": true },
"if_false": { "type": "Literal", "value": false }
}
}
}
]
}

Arithmetic does not accept Decimal or DateTime operands. A string operation on a DateTime uses its RFC 3339 text, so Substring with start 0 and length 10 gives the UTC date (2026-01-31).

Decimal in Group. Min and Max on a Decimal field are exact. To Sum or Average money, store it as an Integer number of minor units (cents) and divide when you display it.

client_function_contract.ts (and the same example in every language) builds each stage with the client's stage helpers, AddFields, SetField, If and Group included, and checks the JSON each one produces.

Execution Model​

Sequential Execution​

By default, Functions execute in sequence:

Function 1 → Function 2 → Function 3 → Result

Each Function waits for the previous to complete before starting.

Conditional Execution​

Use the If Function type for conditional logic:

{
"type": "If",
"condition": {
"type": "FieldEquals",
"value": { "field": "plan", "value": "premium" }
},
"then_functions": [{ "type": "Query", "collection": "premium_features" }],
"else_functions": [{ "type": "Query", "collection": "basic_features" }]
}

condition is a FunctionCondition object (adjacently tagged with type + value), evaluated against the working records — not a string expression. The branches are then_functions and else_functions.

FunctionCondition variants:

  • Field comparisons: FieldEquals, FieldExists, FieldGreaterThan, FieldLessThan, FieldGreaterThanOrEqual, FieldLessThanOrEqual — e.g. { "type": "FieldGreaterThan", "value": { "field": "stock", "value": 0 } }
  • Set/count: HasRecords, CountEquals, CountGreaterThan, CountLessThan
  • Boolean: And, Or, Not — e.g. { "type": "And", "value": { "conditions": [<FunctionCondition>, ...] } }

Branching on a parameter. A condition tests the working records, not the call's parameters: field always names a field on a working record, and a parameter can appear only as the comparison value. To branch on a parameter, copy it onto the working record with SetField first, then test that field. Give the parameter a sentinel default so the branch is decided even when the caller leaves it out:

{
"parameters": {
"project_id": { "required": false, "default": "all" }
},
"functions": [
{ "type": "SetField", "field": "_project", "value": "{{project_id}}" },
{
"type": "If",
"condition": {
"type": "FieldEquals",
"value": { "field": "_project", "value": "all" }
},
"then_functions": [{ "type": "Query", "collection": "tasks", "limit": 100 }],
"else_functions": [
{
"type": "Query",
"collection": "tasks",
"filter": {
"type": "Condition",
"content": { "field": "project_id", "operator": "Eq", "value": "{{project_id}}" }
},
"limit": 100
}
]
}
]
}

If with branches is shown running in client_function_composition.ts.

Loop Execution​

Use the ForEach operation type to iterate over current records:

{
"functions": [
{
"type": "Query",
"collection": "users",
"filter": {
"type": "Condition",
"content": {
"field": "status",
"operator": "Eq",
"value": "pending"
}
}
},
{
"type": "ForEach",
"functions": [
{
"type": "UpdateById",
"collection": "users",
"record_id": "{{id}}",
"updates": { "notified": true }
}
]
}
]
}

How it works:

  • Operates on records from previous operations
  • Executes nested operations for each record
  • Each record's fields are available as variables (e.g., {{id}}, {{email}})

Creating Functions​

What is a Function?​

A Function is a named collection of operations that can be leveraged to perform complex logic and transformations. Each function is versioned for friendly maintenance:

  • Stored in ekoDB
  • Called by label or ID
  • Nested using CallFunction
  • Parameterized with dynamic values

Function Structure​

FieldDescriptionRequired
labelUnique identifierYes
nameHuman-readable nameYes
descriptionWhat the function doesNo
versionSemantic versionNo
parametersInput parametersNo
functionsArray of operationsYes
tagsCategorization tagsNo

Creating a Function​

Minimal Valid Example:

{
"label": "get_user",
"name": "Get User by ID",
"parameters": {
"user_id": {"required": true}
},
"functions": [
{
"type": "FindOne",
"collection": "users",
"key": "id",
"value": "{{user_id}}"
}
]
}

Full Example (With Optional Fields):

{
"label": "user_onboarding",
"name": "User Onboarding Flow",
"description": "Complete new user setup with AI welcome message",
"version": "1.0.0",
"tags": ["onboarding", "users", "ai"],
"parameters": {
"email": { "required": true },
"name": { "required": true }
},
"functions": [
{
"type": "Insert",
"collection": "users",
"record": {
"email": "{{email}}",
"name": "{{name}}"
}
},
{
"type": "Chat",
"messages": [
{
"role": "system",
"content": "You are a friendly onboarding assistant"
},
{
"role": "user",
"content": "Write a welcome message for {{name}}"
}
],
"model": "gpt-4"
}
]
}

What Saving Checks​

Saving a function (admin only) refuses it with 400 when:

  • a step has an unknown type, or a field of the wrong type (a string where a number belongs, for example a "{{n}}" placeholder as a TextSearch limit);
  • run_as is anything other than caller or author;
  • label or name is empty, or functions has no steps;
  • label contains * or is . or ..;
  • a structural parameter reference ({"type": "Parameter", "name": "x"}) names a parameter the function does not declare.

A label that is already taken is refused with 409.

Saving does not check text {{param}} placeholders (an undeclared one is caught only when a call supplies it, as an unknown parameter, or stays literal text), whether the collections a step names exist, or whether a transactional function contains a step that cannot run in a transaction. Those surface when the function runs, so call a new function once with test parameters before relying on it.

Calling a Function​

From Client Library:

const result = await client.callFunction("user_onboarding", {
email: "user@example.com",
name: "John Doe",
});

From REST API:

POST /api/functions/user_onboarding
Content-Type: application/json

{
"email": "user@example.com",
"name": "John Doe"
}

Response format:

A call returns { "records": [...], "stats": {...} }. The record field values follow the same use_typed_values rule as find and query: with use_typed_values enabled they are wrapped ({"type":"String","value":"..."}), and with it disabled they are bare. A client configured for typed values therefore gets the same shape from callFunction as from a read.

This wrapping is applied only on the response to an external caller. Inside the pipeline, and when one function calls another with CallFunction, records flow as bare native values so that {{record.field}} access keeps working in the calling function.

A Return step may set status_code to control the HTTP status of the response (for example 201 after a create, or 404 when a lookup misses). The code sets the actual HTTP status; it does not appear in the response body.

Function Nesting​

Functions can call other Functions for modularity using CallFunction:

{
"label": "process_order",
"name": "Process order",
"functions": [
{
"type": "CallFunction",
"function_label": "validate_inventory",
"params": { "product_id": "{{product_id}}" }
},
{
"type": "CallFunction",
"function_label": "charge_payment",
"params": { "amount": "{{amount}}" }
},
{
"type": "CallFunction",
"function_label": "send_confirmation",
"params": { "order_id": "{{order_id}}" }
}
]
}

Execution:

process_order
├─ validate_inventory
│ ├─ Query products
│ └─ Update inventory
├─ charge_payment
│ └─ HttpRequest to Stripe
└─ send_confirmation
├─ Chat (AI message)
└─ HttpRequest to email API

Versioning​

Why Add Version Metadata?​

  • Evolution - Record a version string as metadata when updating a function
  • Compatibility - Communicate the caller contract expected by the current definition
  • Testing - Use separate labels when old and new definitions must be callable at the same time
  • Operations - Keep deploy and rollback definitions in source control rather than relying on server history

Version Strategy​

{
"label": "calculate_pricing",
"name": "Calculate pricing",
"version": "2.0", // Metadata for the current definition
"functions": [...]
}

Best Practices:

  • Use semantic versioning: major.minor.patch
  • Major version: Breaking changes
  • Minor version: New features (backward compatible)
  • Patch version: Bug fixes
  • Updating a label replaces its current definition. The server attempts a best-effort history snapshot first, but a successful update does not guarantee that the snapshot was stored
  • Neither the public SDKs nor the REST API expose function-history or revert methods. Keep definitions in source control when a dependable rollback path is required
  • To test versions in parallel, save them under separate labels such as calculate_pricing_v1 and calculate_pricing_v2

Calling a Saved Function​

// Call the one current definition stored under this label
await client.callFunction("calculate_pricing", params);

The TypeScript client's callFunction method accepts only the function label or ID and an optional parameters object; it does not take a version selector. The version field is descriptive metadata, not a dispatch key. Updating a function may create a best-effort history snapshot, but that snapshot is neither guaranteed nor independently callable through the same label. Neither the public SDKs nor the REST API provide history inspection or revert methods.

AI Integration​

Chat Functions​

Execute LLM completions with context:

{
"type": "Chat",
"messages": [
{
"role": "system",
"content": "You are a data analyst"
},
{
"role": "user",
"content": "Analyze this data: {{query_results}}"
}
],
"model": "gpt-4",
"temperature": 0.7,
"max_tokens": 1000
}

Supported Models:

  • OpenAI: gpt-4, gpt-4-turbo, gpt-3.5-turbo
  • Anthropic: claude-3-opus, claude-3-sonnet
  • Perplexity: pplx-7b-online, pplx-70b-online

Embedding Functions​

Generate vector embeddings for text:

{
"type": "Embed",
"input_field": "description",
"output_field": "description_vector",
"model": "text-embedding-ada-002"
}

Use Cases:

  • Semantic search
  • Document similarity
  • Recommendation systems
  • Clustering

RAG Workflows​

Build complete RAG pipelines by combining search and AI:

{
"label": "answer_with_context",
"name": "Answer with context",
"parameters": {
"query": { "required": true },
"context": { "required": true }
},
"functions": [
{
"type": "Chat",
"messages": [
{
"role": "system",
"content": "Answer using only the provided context"
},
{
"role": "user",
"content": "Context: {{context}}\n\nQuestion: {{query}}"
}
],
"model": "gpt-4"
}
]
}

Retrieve the context in your application (for example with a text or hybrid search) and pass it as the context parameter. A stage's output is not bound to a named parameter such as search_results: only a stage that yields a single record exposes that record's fields as parameters, and HttpRequest also stores its response under its output_field. The Chat stage returns a record whose response field holds the model's answer.

Note: For true vector search RAG, first generate embeddings for your documents using the Embed operation, then use VectorSearch to find similar content.

External Integrations​

HTTP Requests​

Call external APIs from Functions:

{
"type": "HttpRequest",
"method": "POST",
"url": "https://api.stripe.com/v1/charges",
"headers": {
"Authorization": "Bearer {{stripe_key}}",
"Content-Type": "application/x-www-form-urlencoded"
},
"body": {
"amount": "{{amount}}",
"currency": "usd",
"source": "{{token}}"
},
"timeout_seconds": 15,
"output_field": "charge_result"
}

Response Handling:

The HTTP response is stored in the specified output_field (default: http_response):

timeout_seconds optionally limits the outbound request. output_field controls where the parsed response is written so later stages can reference it.

  • JSON responses are automatically parsed into native Objects/Arrays
  • Non-JSON responses (HTML, plain text) are stored as Strings

You can reference the response in subsequent stages using the field name specified in output_field (e.g., {{charge_result}} in the example above).

Use Cases:

  • Payment processing (Stripe, PayPal)
  • Email services (SendGrid, Mailgun)
  • SMS notifications (Twilio)
  • Webhook triggers
  • Third-party API integration

Performance Considerations​

Execution Time​

  • Operation overhead: ~1-5ms per operation
  • Network calls: Variable (external APIs, AI)
  • Database operations: Sub-millisecond for queries
  • Total Function time: Sum of all operation times

Optimization Strategies​

  1. Batch operations instead of loops when possible
  2. Limit result sets with filters and projections
  3. Filter early - Reduce data before expensive operations
  4. Cache Function definitions (auto-cached by ekoDB)
  5. Minimize external HTTP calls

Stale-While-Revalidate (SWR) Pattern​

Functions are perfect for the SWR pattern, which dramatically improves perceived performance by serving cached results while fetching fresh data in the background.

How it works:

1. Client requests Function execution
2. Return cached result immediately (if exists)
3. Execute Function in background
4. Update cache with fresh result
5. Next request gets updated data

Benefits:

  • ⚡ Instant response - Users see data immediately
  • 🔄 Always fresh - Background updates keep data current
  • 📉 Reduced load - Fewer Function executions
  • 🎯 Better UX - No loading spinners for cached data

When to use:

  • ✅ Dashboard summaries that don't change frequently
  • ✅ User profile data (name, email, settings)
  • ✅ Product catalogs with periodic updates
  • ✅ Analytics data that's expensive to compute
  • ❌ Real-time data (stock prices, live scores)
  • ❌ User-specific transactional data (cart, orders)

Example pattern:

// Client-side SWR with Functions
async function getUserDashboard(userId: string) {
// 1. Return cached data immediately
const cached = cache.get(`dashboard:${userId}`);
if (cached) {
// Serve stale data instantly
displayDashboard(cached);

// 2. Revalidate in background
client.callFunction("user_dashboard", { user_id: userId }).then((fresh) => {
cache.set(`dashboard:${userId}`, fresh);
displayDashboard(fresh); // Update UI with fresh data
});

return cached;
}

// 3. No cache - fetch and display
const data = await client.callFunction("user_dashboard", { user_id: userId });
cache.set(`dashboard:${userId}`, data);
return data;
}

Server-side caching:

Functions can also implement internal caching for even better performance:

{
"label": "expensive_analytics",
"name": "Expensive analytics",
"functions": [
{
"type": "Query",
"collection": "events",
"filter": {
"type": "Condition",
"content": {
"field": "date",
"operator": "Eq",
"value": "{{today}}"
}
}
},
{
"type": "Group",
"by_fields": ["category"],
"functions": [{ "output_field": "count", "operation": "Count" }]
}
]
}

Call this Function with a cache key and TTL, and ekoDB can cache results server-side for all clients.

Example Code

SWR Pattern Examples in all languages:

Edge Cache Pattern - Use ekoDB as an edge cache with external API caching:

Best Practices​

DO:

  • ✅ Keep Functions focused and single-purpose
  • ✅ Use meaningful labels and descriptions
  • ✅ Document parameters clearly
  • ✅ Version Functions properly
  • ✅ Test with sample data before production

DON'T:

  • ❌ Create mega-Functions with 50+ operations
  • ❌ Use Functions for simple single operations
  • ❌ Hard-code values (use parameters)
  • ❌ Nest Functions more than 3-4 levels deep
  • ❌ Ignore error handling

Error Handling​

Operation-Level Errors​

If an operation fails:

  1. Execution stops immediately
  2. Error details are returned
  3. No rollback (unless in transaction)
  4. Caller receives error response
{
"error": true,
"operation_index": 2,
"operation_type": "Chat",
"message": "API rate limit exceeded",
"details": {...}
}

Error Recovery​

To catch a failing step and run fallback logic, use TryCatch (the step's error is bound to output_error_field):

{
"type": "TryCatch",
"try_functions": [
{
"type": "Chat",
"messages": [{ "role": "user", "content": "{{question}}" }]
}
],
"catch_functions": [
{
"type": "Insert",
"collection": "error_log",
"record": { "error": "{{error}}" }
}
],
"output_error_field": "error"
}

If branches on a FunctionCondition evaluated against the working records — note condition is an object (not a string), and the branches are then_functions / else_functions:

{
"type": "If",
"condition": { "type": "HasRecords" },
"then_functions": [
{ "type": "Insert", "collection": "audit", "record": { "event": "found" } }
],
"else_functions": []
}

Transactions​

Wrap operations in transactions for atomicity:

{
"transaction_config": { "enabled": true, "auto_rollback": true },
"functions": [
{
"type": "Update",
"collection": "inventory",
"filter": {"type": "Condition", "content": {"field": "sku", "operator": "Eq", "value": "SKU001"}},
"updates": {"reserved": true}
},
{
"type": "Insert",
"collection": "orders",
"record": {"id": "ORDER001", "sku": "SKU001"}
}
]
}

If any operation fails, all changes are rolled back.

Security​

Reading and Copying Stored Functions​

In server version 0.80.0, generic data reads of functions_ and agent_function_versions_ replace inline secrets with placeholders such as <redacted:/path/to/field>. Administrators can request raw values with include_secrets=true. A write containing a placeholder returns 400. Before copying a function or its versions to another deployment, supply the destination's secrets or retrieve the required raw values with an admin token. See System collection secrets for the same rules on webhook system collections and safe handling of exports.

Permission Model​

The same rules apply to every caller: an application over REST or a client library, a schedule, a webhook, a custom route, or an agent through call_function. These checks are enforced in the default enforce mode. On an instance running in shadow mode, a refused call grant, step permission or run identity is recorded as access_would_deny and allowed to proceed; admin-only routes, request validation and a function step's write to a system collection are enforced in both modes.

  • Defining a function is admin-gated. Saving, replacing, listing and deleting a function definition, and creating a schedule for one, need an admin key.
  • Calling a function needs a call grant. An admin key calls every function. Any other key needs a grant in its function_permissions: a function label, a label prefix ending in one *, or * for every function. A call that no grant covers is refused with 403 on POST /api/functions/{label_or_id} and on custom routes. Functions shows how grants are given and what a pattern may hold.
  • Every step runs as the identity the function declares. run_as: caller (the default for a function saved without one) applies the calling key's grants; run_as: author applies the grants of the key recorded as the function's author (created_by), read from the key store when the call runs.
  • Every step is checked against that identity, after its {{param}} placeholders are filled in, so a collection a parameter chose is decided as the name it became. A step nested in If, ForEach, TryCatch, Parallel or Validate.on_error is decided when it runs; the container itself touches nothing. A refused step fails the function with 403 and has no effect.
  • An agent's call_function runs the function for the key behind the session, through the same call grant and the same run_as, and the session's collection scope and tool configuration are checked at call time against every collection the function reaches, including nested stages, called functions and collections named by a {{param}}. A function outside that scope is refused. A run with no key behind it does not run a function.
  • A function's writes are audited. Every write step that succeeds adds one audit entry, and steps cannot write the audit collection. Security lists the events.

What each step needs​

Each kind of step follows the rule the REST route for the same operation applies:

StepNeeds
FindAll, Query, FindById, FindOne, VectorSearch, HybridSearch, TextSearchRead on the collection
Insert, BatchInsert, UpdateById, UpdateWithAction, Increment, Push, DeleteById, BatchDeleteWrite on the collection
Update, Delete, FindOneAndUpdate, UpsertRead and write on the collection, because they select what they change or return it
KvGet, KvExistsA key-value read grant covering the key
KvSet, KvDeleteA key-value write grant covering the key
KvQueryNothing up front: it returns only the keys the identity may read
IdempotencyClaim, RateLimit, LockAcquire, LockReleaseA key-value write grant covering idempotency:{key}, rate:{key}: or lock:{key}
HttpRequest, SWR, EmailSendAn admin identity: no grant covers sending data out of the server
Chat, EmbedNo grant of their own
CallFunctionA call grant covering the callee, on the identity the calling function runs as. The callee then runs under its own run_as
The transformation, crypto and encoding steps, Sleep, savepointsNothing: they touch no stored data and send nothing out
ReturnNothing is checked: its fields are the response, so what a function returns is visible to its caller

The identity's field limits apply as well. A field a step names in a filter, a sort, a FindOne key, an Upsert key or a TextSearch field list must be readable, or the step is refused, because which records match would reveal it. The records a read or write step returns are projected by the identity's select_fields and exclude_fields. The fields an Insert, BatchInsert, Update, UpdateById, FindOneAndUpdate, UpdateWithAction, Increment, Push or Upsert writes (and its ttl) must be in writable_fields. The key-value entries linked from a record a step deletes need a key-value write grant. When the identity limits what it reads in a collection, a TextSearch that names no fields and a HybridSearch are refused, because the engine would search every field, and a VectorSearch needs the default vector field to be readable.

Some collections are never writable from a step. A step that writes the records of stored functions and their saved versions, of schedules or of webhook receivers is refused for every identity, an admin's included. Their own routes and tools record the saving key; an admin key's generic write also reaches them, because that is how a ripple peer replicates them. The audit collection is refused the same way.

Single-pass substitution applies to every step. A parameter value, step result or dotted-path value that holds placeholder text such as {{other}} or {{env.NAME}} is stored as written; only the placeholders in the function's own definition are filled in.

Limits​

  • A removed grant stays usable through a token already issued until it expires.
  • A TryCatch can catch a refused step, so a function can carry on after a refusal.
  • An author's key is read when the call starts and again at each CallFunction hop, not between the steps of one running function.
  • Outbound steps need an admin identity, and Chat and Embed send what the step names to a model provider for any key that may call the function.
  • Under run_as: author, a collection a {{param}} chooses is decided against the author's grants.
  • What a function returns, {{env.NAME}} values included, is visible to every key granted the function.

See Functions for how this looks from an application and from an agent, and for what changes on an instance that already has functions.

Parameter Validation​

Parameters are checked before execution:

  • Defaults are applied to omitted optional parameters
  • Missing required parameters are rejected
  • Unknown parameter names are rejected (ekoDB-supplied system parameters are exempt)

ekoDB does not check parameter types or enum values; validate those in the caller, or with a Validate stage.

Injection Prevention​

ekoDB automatically:

  • ✅ Sanitizes all parameter inputs
  • ✅ Prevents NoSQL injection
  • ✅ Escapes special characters
  • ✅ Validates JSON structure

Safe:

{
"filter": {
"type": "Condition",
"content": { "field": "email", "operator": "Eq", "value": "{{user_email}}" }
}
}

User cannot inject malicious queries.

JWT Signing and Verification​

JwtSign and JwtVerify support both symmetric and asymmetric algorithms via the algorithm parameter, which defaults to HS256:

FamilyAlgorithmssecret holds
HMACHS256, HS384, HS512A shared secret
RSA (PKCS#1 v1.5)RS256, RS384, RS512A PEM private key to sign, the matching PEM public key to verify
RSA-PSSPS256, PS384, PS512Same as RSA above
ECDSAES256, ES384A PEM private/public key pair
EdDSAEdDSAA PEM private/public key pair

none is rejected outright — there is no way to issue or accept an unsigned token.

Asymmetric algorithms are what let you verify a token you didn't issue yourself without standing up a separate signing service — a GitHub App installation token or a Google service-account JWT both arrive signed RS256, and JwtVerify checks them against the issuer's public key directly.

{
"type": "JwtVerify",
"algorithm": "RS256",
"token_field": "installation_token",
"secret": "{{env.GITHUB_APP_PUBLIC_KEY}}",
"output_field": "claims"
}

Key formats. RSA (RS* / PS*) accepts both PKCS#1 (BEGIN RSA PRIVATE KEY, the format GitHub Apps hand out) and PKCS#8 (BEGIN PRIVATE KEY).

ES* and EdDSA are PKCS#8 only. The SEC1 form (BEGIN EC PRIVATE KEY) — what a plain openssl ecparam -genkey -name prime256v1 produces — is rejected with a clear error rather than silently mishandled. Convert an existing SEC1 key with:

openssl pkcs8 -topk8 -nocrypt -in ec_key_sec1.pem -out ec_key_pkcs8.pem

Both secret and algorithm must be operator-supplied, not caller-supplied. Neither accepts a call-time parameter — secret may be a literal or {{env.NAME}}, and algorithm must be a literal (not even {{env.NAME}}). This is enforced because a caller who could choose either could forge a token: naming HS256 against a stage whose secret holds an asymmetric public key turns that public key into an HMAC secret, and a caller-supplied signing key needs no forging at all.

Use Cases​

1. User Authentication Flow​

{
"label": "get_user_by_email",
"name": "Get user by email",
"parameters": {
"email": { "required": true }
},
"functions": [
{
"type": "FindOne",
"collection": "users",
"key": "email",
"value": "{{email}}"
}
]
}

2. E-commerce Order Processing​

{
"label": "create_order",
"name": "Create order",
"parameters": {
"user_id": { "required": true },
"product_id": { "required": true }
},
"functions": [
{
"type": "FindById",
"collection": "products",
"record_id": "{{product_id}}"
},
{
"type": "Insert",
"collection": "orders",
"record": {
"user_id": "{{user_id}}",
"product_id": "{{product_id}}",
"status": "pending"
}
}
]
}

3. AI Content Moderation​

{
"label": "moderate_content",
"name": "Moderate content",
"parameters": {
"content": { "required": true }
},
"functions": [
{
"type": "Chat",
"messages": [
{
"role": "system",
"content": "Analyze if content is appropriate and respond with 'SAFE' or 'UNSAFE'"
},
{
"role": "user",
"content": "{{content}}"
}
],
"model": "gpt-4"
}
]
}

4. Data Analytics Pipeline​

{
"label": "event_summary",
"name": "Event summary",
"parameters": {
"date": { "required": true }
},
"functions": [
{
"type": "Query",
"collection": "events",
"filter": {
"type": "Condition",
"content": {
"field": "date",
"operator": "Eq",
"value": "{{date}}"
}
}
},
{
"type": "Count",
"output_field": "total_events"
}
]
}

Comparison with Alternatives​

vs. Stored Procedures (SQL)​

FeatureekoDB FunctionsSQL Stored Procedures
LanguageJSON (declarative)SQL (procedural)
VersioningBuilt-inManual
AI IntegrationNativeNone
External APIsYesLimited
PortabilityJSON formatDatabase-specific

vs. Cloud Functions (AWS Lambda, etc.)​

FeatureekoDB FunctionsCloud Functions
ExecutionServer-side in ekoDBSeparate compute
NetworkSingle callMultiple calls
StateDirect DB accessMust connect to DB
DeploymentJSON definitionCode deployment
CostIncludedPer-invocation

vs. Application Code​

FeatureekoDB FunctionsApplication Code
LocationServer-sideClient-side
ReusabilityAll clientsSingle codebase
PerformanceLow latencyMultiple round-trips
VersioningBuilt-inGit/deployment
TestingIsolatedFull app context

Next Steps​

📚 Explore Function Examples​

Complete working examples in all languages:

  • Function Composition Examples - Full-featured examples:

    • Rust: client_function_composition.rs
    • Python: client_function_composition.py
    • TypeScript: client_function_composition.ts
    • JavaScript: client_function_composition.js
    • Go: client_functions.go
    • Kotlin: ClientFunctionComposition.kt
  • RAG & AI Examples - Retrieval-augmented generation:

    • Rust: rag_conversation_system.rs
    • Python: rag_conversation_system.py
    • TypeScript: rag_conversation_system.ts
    • Go: rag_conversation_system.go
    • Kotlin: RagConversationSystem.kt
  • SWR Pattern - Stale-while-revalidate with Functions:

Learning Path​

  1. Learn by example - Browse the GitHub examples above
  2. Start simple - Create a basic Query Function
  3. Add parameters - Make Functions dynamic
  4. Compose Functions - Combine Functions for workflows
  5. Integrate AI - Add Chat and Embed Functions

Need help? Submit a support ticket or open an issue