Liking cljdoc? Tell your friends :D

Getting started

From nothing to a deployed model and your first query.

1. Install the CLI

curl -fsSL https://raw.githubusercontent.com/synthigy/tooling/main/install.sh | sh

Windows:

irm https://raw.githubusercontent.com/synthigy/tooling/main/install.ps1 | iex

2. Start an instance

mkdir my-app && cd my-app
synthigy env init        # this folder gets its own instance in .synthigy/
synthigy up

env init gives the instance its own engine port, 7887 unless that is taken, and prints it; the examples below use 7887, so use the port it printed. The first up downloads a Java runtime into ~/.synthigy, starts the portal and opens it in your browser. The portal takes a free port each time it starts: up prints the address, and synthigy portal opens it again whenever you need it. Pick a bundle — sqlite needs nothing else; postgres needs a database you created — and check it: Check file for SQLite, Test connection for PostgreSQL (the first check downloads the engine). Choose where uploaded files are kept, local disk or an S3 bucket (Test bucket). Launch unlocks once the checks pass. When the engine is up, the portal asks for the first superuser.

synthigy up --bundle sqlite skips the choice.

The engine now serves on its port, here http://localhost:7887, with the console at http://localhost:7887/console. Sign in there as the superuser. The portal runs the instance; the console administers it (CONSOLE.md).

3. Model your data

In the console open Tools → Data modeling. Create a dataset, Movies, with one entity, Movie, and two attributes: Title (string, mandatory) and Release year (int). Leave access control off for now: an entity with it off is open to every signed-in caller (ACCESS.md). Press Deploy; Synthigy creates the table.

In the API the names are snake case: entity movie, attributes title and release_year. Relations, the other types and versions: MODELING.md.

4. Let an application in

synthigy iam add-client "My App" --id my-app --type confidential \
  --grant client_credentials --role "Dataset Explorer" --api Synthigy --local

add-client prints the secret once. The application's identity is three lines; add them to .synthigy/.env, the file env init created:

SYNTHIGY_ENDPOINT=http://localhost:7887
SYNTHIGY_CLIENT_ID=my-app
SYNTHIGY_CLIENT_SECRET=<secret>

synthigy exec hands them to your program, and synthigy token mints tokens from them. env init made the file private (mode 0600) and keeps .synthigy/ out of git. To have the three checked first, run synthigy connect http://localhost:7887 --client-id my-app instead of editing the file: it asks for the secret, mints one token to prove they work, and writes the same lines.

Dataset Explorer lets the application read the model, which code generation needs. What data it may read and write is decided by your entities' access rules — and an entity with access control off is open to every signed-in client (ACCESS.md).

5. Write, then read

One request may carry several operations. Writes run before reads, so this creates a movie and reads it back:

curl -s http://localhost:7887/data \
  -H "Authorization: Bearer $(synthigy token)" \
  -H 'Content-Type: application/json' \
  -d '{"operations": [
        {"op": "stack", "entity": "movie",
         "data": {"title": "Dune", "release_year": 2021}},
        {"op": "search", "entity": "movie", "args": {"_limit": 5},
         "selections": {"title": null, "release_year": null}}]}'

The second result is the search:

{"ok": true, "data": [{"xid": "…", "title": "Dune", "release_year": 2021}]}

Or from code, with an SDK, run under synthigy exec so it finds the server and the identity on its own (SDKS.md):

npm install @synthigy/sdk
synthigy exec -- node app.js

  • DATA.md — every operation of the data API
  • XSQL.md — queries as documents, typed code from them
  • SIGN_IN.md — signing users in to your application
  • OPERATIONS.md — running it for real: service, upgrades, backups

Can you improve this documentation?Edit on GitHub

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
× close