You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
*[**AI Applications**](./ai.md): Building AI-powered apps.
1
+
# Introduction
2
+
3
+
**ObjectQL** is a protocol-first application engine. It rethinks backend development by treating everything—Data Models, Queries, and Logic—as **structured data** rather than code strings.
4
+
5
+
## The Core Philosophy
6
+
7
+
### 1. The JSON Protocol
8
+
In traditional development, you write SQL strings (`SELECT * FROM users`) or use fluent builders (`db.select('users')`).
9
+
In ObjectQL, the query **IS** the data structure.
10
+
11
+
```json
12
+
// Find users where age > 18
13
+
{
14
+
"op": "find",
15
+
"object": "user",
16
+
"args": {
17
+
"filters": [["age", ">", 18]]
18
+
}
19
+
}
20
+
```
21
+
22
+
This makes the protocol:
23
+
***Universal**: Can be generated by any client (JS, Python, Swift, or LLMs).
24
+
***Serialization-ready**: Pass it over HTTP, WebSocket, or save it to a file.
25
+
***Secure**: Zero SQL injection risk by design.
26
+
27
+
### 2. Metadata as Source of Truth
28
+
Instead of defining TypeScript classes or SQL DDL, you define your business domain in declarative YAML.
ObjectQL provides a built-in mechanism to aggregate data from multiple services into a single unified graph. This is similar to **GraphQL Federation** or Salesforce's **External Objects**, but strictly for the ObjectQL protocol.
4
+
5
+
## Concept: Remote Remotes
6
+
7
+
You can configure an ObjectQL instance to act as a **Gateway**. It connects to other ObjectQL instances, downloads their metadata (Schema), and automatically creates proxy drivers for them.
8
+
9
+
***Source of Truth**: The microservice defines the object (`user.object.yml`).
10
+
***Proxy**: The gateway sees a virtual object (`user`) and forwards all queries (Find, Update, Actions) to the microservice.
11
+
12
+
## Configuration
13
+
14
+
### The Subgraph (Service A)
15
+
16
+
This is a standard ObjectQL service running standard drivers (SQL/Mongo).
17
+
It must expose the metadata API (default in `@objectql/server`).
ObjectQL uses a **JSON-based Protocol** for all data operations. Unlike SQL (strings) or Query Builders (chained methods), ObjectQL queries are **Data Structures**.
4
+
5
+
This design makes it strictly typed, easy to serialise/transport over HTTP, and safe from injection—perfect for both human developers and AI Agents.
6
+
7
+
## The `find()` Operation
8
+
9
+
The `find` method recovers a list of records matching specific criteria.
10
+
11
+
```typescript
12
+
const products =awaitapp.object('product').find({
13
+
filters: [
14
+
['category', '=', 'electronics'],
15
+
['price', '>', 500]
16
+
],
17
+
fields: ['name', 'price', 'category'],
18
+
sort: ['-price'], // Descending
19
+
skip: 0,
20
+
limit: 10
21
+
});
22
+
```
23
+
24
+
### Filters
25
+
26
+
Filters are defined as a 2D array: `[[ field, operator, value ]]`.
27
+
28
+
**Implicit AND**:
29
+
```typescript
30
+
filters: [
31
+
['status', '=', 'active'],
32
+
['stock', '>', 0]
33
+
]
34
+
// SQL: WHERE status = 'active' AND stock > 0
35
+
```
36
+
37
+
**Explicit OR**:
38
+
Use the `_or` special operator in complex filters (see advanced docs).
39
+
40
+
### Sorting
41
+
42
+
*`field`: Ascending.
43
+
*`-field`: Descending.
44
+
45
+
## CRUD Operations
46
+
47
+
### Create (Insert)
48
+
49
+
```typescript
50
+
const id =awaitapp.object('user').insert({
51
+
name: "Alice",
52
+
email: "alice@example.com",
53
+
role: "admin"
54
+
});
55
+
```
56
+
57
+
### Update
58
+
59
+
Updates are always bulk operations targeted by `filters`. To update a single record, filter by ID.
60
+
61
+
```typescript
62
+
// Update specific record
63
+
awaitapp.object('user').update(
64
+
{ filters: [['_id', '=', '123']] }, // Target
65
+
{ doc: { status: 'active' } } // Change
66
+
);
67
+
68
+
// Bulk update
69
+
awaitapp.object('product').update(
70
+
{ filters: [['stock', '=', 0]] },
71
+
{ doc: { status: 'out_of_stock' } }
72
+
);
73
+
```
74
+
75
+
### Delete
76
+
77
+
```typescript
78
+
// Delete specific record
79
+
awaitapp.object('user').delete({
80
+
filters: [['_id', '=', '123']]
81
+
});
82
+
```
83
+
84
+
## Relationships (Joins)
85
+
86
+
ObjectQL handles joins automatically via the `expand` option or dot-notation in `fields` (depending on the driver implementation).
0 commit comments