Skip to main content

Getting Started

The first TeaQL journey should prove one complete loop:

model
  -> evaluate
  -> generate
  -> build or test
  -> execute a generated query
  -> change the model
  -> regenerate and review

Do not begin by reading every runtime customization page. First prove that the model, generator, generated API, and runtime work together.

Choose a Path​

Start with an Example​

Use Start from Example when you want an AI coding agent to create and verify a workspace from a small business description.

This is currently the most complete cross-stack entry path because the agent can inspect the generated workspace and use the build command that the selected generator version actually produces.

Evaluate Java​

Use the Java path when you need Spring Boot integration, the mature Java query API, and enterprise runtime customization:

  1. Generate a Java library and runnable application from a reviewed model.
  2. Build the generated project with the build wrapper or command included in that project.
  3. Locate the generated entity and Q request source.
  4. Execute the pattern in First Query.
  5. Follow Regenerate and Review.

The public Java documentation does not yet define one universal local generation command for every generator distribution. Use the command exposed by the selected TeaQL client or Agent Kit. TeaQL Maven plugin 1.1.0 exposes a dynamic generate goal; run mvn io.teaql:teaql-maven-plugin:1.1.0:list-services, then pass the selected target through -Dservice.

Evaluate Rust​

Use the Rust path when you need generated Rust APIs, provider-based runtimes, or single-binary deployment:

Follow the complete Rust Quick Start to generate and test both targets, start SQLite, execute an intent-declared query, persist an audited mutation, and review a regeneration diff.

cargo teaql --help
cargo teaql services
cargo teaql evaluate --input model/main.xml
cargo teaql rust-lib-core --input model/main.xml --output generated/rust-lib-core
cargo teaql rust-app-console --input model/main.xml --output generated/rust-app-console

The installed client is authoritative for available arguments. The currently generated console manifest expects the library at ../rust-lib-core/lib, so keep these output directories side by side. Run cargo test from each generated crate, then inspect the generated Q API before writing application code.

For lookup details, continue with The Cargo Toolchain and Rust Overview.

What Success Looks Like​

A first run is successful only when you can show all of the following:

  • The model evaluates without unresolved errors.
  • Generation completes and produces the expected workspace or library.
  • The generated project builds or its tests run.
  • A generated entity and its request methods can be located in source.
  • One query declares comment and purpose before execution.
  • A small model edit produces a predictable generated API diff.
  • No generated source was used as a handwritten customization point.

If the First Run Fails​

Read Troubleshoot First Run. For evaluation or generation failures, start with the Markdown report printed by the client rather than editing generated files.