Skip to main content

Verify against the examples

The ekodb-client examples are runnable programs, one set per language: Rust, Python, TypeScript, JavaScript, Go and Kotlin. The example suite (make test-examples in the ekodb-client repository) runs them against a live ekoDB server, so each example is a check that the behavior it shows works today. That makes the examples the tested contract for the client libraries: when a page in these docs and an example disagree, trust the example and tell us so the page is fixed.

Before concluding ekoDB cannot do something​

  1. Find the example for the topic in the table below, or search the examples folder for the method or stage you need.
  2. Read the docs page that owns the topic (linked in the table).
  3. If neither answers it, ask through support or an issue on the client repository, rather than building a workaround on a guess.

Many "ekoDB can't" conclusions come from a default or limit that was not looked up: a query that returned 1,000 records because no limit was passed, a field refused because its type was pinned by an earlier write, a function branch that tested a parameter instead of a record. The pages linked below state those defaults and limits.

Topic to example​

The TypeScript file is linked; the same example exists for Python, Go and Rust under the same name in examples/<language>/ (Rust in examples/rust/examples/), and for Kotlin in PascalCase under examples/kotlin/examples/ (ClientSimpleCrud.kt).

TopicExampleDocs page
Insert, read, update, deleteclient_simple_crud.tsBasic Operations
Filters, sorting, limitclient_query_builder.tsQuerying with Filters, Limits and Paging
Selecting or excluding fieldsprojection_example.tsQuery Expressions
Joins across collectionsclient_joins.tsAdvanced Operations: Joins
Distinct valuesclient_distinct_values.tsThe example is the reference (distinctValues / distinct_values)
Schemas: types, unique, enums, requiredclient_schema.tsCollections & Schemas, Data Types
Creating, listing and deleting collectionsclient_collection_management.tsCollections & Schemas
Batch insert, update, deleteclient_batch_operations.tsBatch Operations
Record TTLclient_document_ttl.tsAdvanced Operations: TTL
Key-value storeclient_kv_operations.tsKey-Value Store
Transactionsclient_transactions.tsTransactions
Text and vector searchclient_search.tsIndexes, Vector Search
Queries and subscriptions over WebSocketclient_simple_websocket.ts, client_websocket_subscribe.tsReal-Time
Saving and calling functionsclient_functions.tsFunctions
Query, sort, limit and Group in functionsclient_functions_advanced.tsFunctions Architecture
If, CallFunction and compositionclient_function_composition.tsFunctions Architecture
The JSON of every stage, AddFields included (an offline check)client_function_contract.tsFunctions Architecture
Search steps in functionsclient_functions_search.tsFunctions Architecture
Stale-while-revalidate cachingclient_swr_pattern.tsFunctions Architecture
Sign-up and login as functionsclient_jwt_auth_flow.tsFunctions Architecture
Schedulesclient_schedules.tsScheduled Functions
Chat sessionsclient_chat_sessions.ts, client_chat_basic.tsChat & RAG
Retrieval-augmented chatrag_conversation_system.tsChat & RAG
API keys and grants (admin)client_admin.tsSecurity

Running the examples yourself​

The examples need a running ekoDB instance and credentials for it; the examples README explains the environment they read. From a clone of the ekodb-client repository, make test-examples runs every language's examples against that instance, and the README lists the per-language targets. The AI examples call a model provider, so a full run can incur provider charges; the README states which models they use and the limits they set.

For coding agents​

If you are an AI coding agent working on an application that uses ekoDB:

  • Read the example before building a workaround. When something seems unsupported, find the example for it in the table above and read how it does it. A workaround (storing JSON as a string, reading a whole collection, keeping a side table for uniqueness) usually means a documented option was missed.
  • Never record "ekoDB can't X" without evidence. Write it into code comments, notes or memory only with a link to the example or the docs page that says so. Without one, ask your user, who can ask ekoDB support.
  • Use the stated defaults and limits. Pass an explicit limit on every query, and look up a limit on its docs page instead of inferring it from one response.