QueryLab

Documentation

Everything you need to know to build powerful queries with QueryLab.

1. Core Concepts

QueryLab is built around a recursive tree architecture. Every query starts with a Root Group. A group can contain multiple Rules or even other Groups (nested groups).

  • Rule GroupA container that holds rules and determines how they are combined logically (using either "AND" or "OR").
  • RuleA single condition consisting of a Field (e.g., "age"), an Operator(e.g., ">"), and a Value(e.g., "18").

2. Schema-Driven Architecture

Unlike basic query builders, QueryLab strictly adheres to a predefined JSON schema. This means:

  • Fields are automatically populated from your schema definitions.
  • Operators dynamically change based on the field's data type (e.g., only "string" fields get the "contains" operator).
  • Input components adapt intelligently (e.g., date pickers for "date" fields, dropdowns for "enum" fields).
// Example Schema Definition const userSchema = [ { name: "age", type: "number" }, { name: "role", type: "enum", options: ["admin", "user"] } ];

3. Exporting Queries

Once you have built your query tree visually, QueryLab parses it instantly into multiple formats.

SQL Output

Generates standard ANSI SQL "WHERE" clauses, wrapping nested groups in parentheses automatically to preserve logical order of operations.

MongoDB Output

Outputs valid MongoDB JSON filter objects using standard query operators like "$and", "$or", "$eq", "$gt", etc.

4. Advanced State Management

QueryLab leverages Zustand for robust, predictable state management. The entire query tree is fully reactive.

  • Undo/Redo: Build with confidence knowing you can revert accidental deletions.
  • Hydration: Load existing queries from your backend seamlessly by passing a JSON string to the store.
  • Performance: Subscriptions are highly optimized, ensuring only modified components re-render during complex drag-and-drop operations.

5. Customizing Operators

You can easily extend the engine to support custom database operators (like PostGIS spatial queries or Elasticsearch fuzzy matching).

// Adding a custom operator import { registerOperator } from 'querylab/core'; registerOperator({ id: 'near', label: 'Is Near', supportedTypes: ['location'], sqlGenerator: (field, value) => `ST_DWithin(${field}, ${value}, 1000)` });