@harperfast/template-vue-studio 1.13.5 → 1.13.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/.agents/skills/harper-best-practices/AGENTS.md +1260 -1113
  2. package/.agents/skills/harper-best-practices/rules/automatic-apis.md +118 -83
  3. package/.agents/skills/harper-best-practices/rules/checking-authentication.md +244 -256
  4. package/.agents/skills/harper-best-practices/rules/custom-resources.md +37 -42
  5. package/.agents/skills/harper-best-practices/rules/defining-relationships.md +86 -49
  6. package/.agents/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
  7. package/.agents/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
  8. package/.agents/skills/harper-best-practices/rules/load-env.md +27 -30
  9. package/.agents/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
  10. package/.agents/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
  11. package/.agents/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
  12. package/.agents/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
  13. package/.agents/skills/harper-best-practices/rules/vector-indexing.md +77 -68
  14. package/.agents/skills/harper-mcp/AGENTS.md +228 -155
  15. package/.agents/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
  16. package/.agents/skills/harper-mcp/rules/enabling-mcp.md +104 -92
  17. package/.agents/skills/harper-mcp/rules/rate-limiting.md +95 -28
  18. package/agent/skills/harper-best-practices/AGENTS.md +1260 -1113
  19. package/agent/skills/harper-best-practices/rules/automatic-apis.md +118 -83
  20. package/agent/skills/harper-best-practices/rules/checking-authentication.md +244 -256
  21. package/agent/skills/harper-best-practices/rules/custom-resources.md +37 -42
  22. package/agent/skills/harper-best-practices/rules/defining-relationships.md +86 -49
  23. package/agent/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
  24. package/agent/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
  25. package/agent/skills/harper-best-practices/rules/load-env.md +27 -30
  26. package/agent/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
  27. package/agent/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
  28. package/agent/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
  29. package/agent/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
  30. package/agent/skills/harper-best-practices/rules/vector-indexing.md +77 -68
  31. package/agent/skills/harper-mcp/AGENTS.md +228 -155
  32. package/agent/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
  33. package/agent/skills/harper-mcp/rules/enabling-mcp.md +104 -92
  34. package/agent/skills/harper-mcp/rules/rate-limiting.md +95 -28
  35. package/package.json +1 -1
  36. package/skills-lock.json +2 -2
@@ -7,8 +7,8 @@ metadata:
7
7
  - reference/v5/resources/overview.md#Custom External Data Source
8
8
  - reference/v5/resources/overview.md#Exporting Resources as Endpoints
9
9
  - reference/v5/components/javascript-environment.md#Module Formats
10
- sourceCommit: e73e5efb2823cc52caf7a6458d67fbcff3bbff2c
11
- inputHash: b2f8749a92d64168
10
+ sourceCommit: 6cd8a2ea6372924486aac46a5d96ba00c10eff07
11
+ inputHash: 01f0a9c7088b116a
12
12
  ---
13
13
 
14
14
  # Custom Resources
@@ -19,23 +19,23 @@ Instructions for the agent to follow when defining custom REST endpoints with Ja
19
19
 
20
20
  ## When to Use
21
21
 
22
- Apply this rule when you need to create custom HTTP endpoints, wrap external APIs, or register routes programmatically in a Harper application. Use it any time business logic must live outside a table-backed schema, or when you need fine-grained control over URL shape and path parameters.
22
+ Apply this rule when you need to create custom HTTP endpoints, wrap external APIs, or register routes programmatically in a Harper application. Use it any time business logic must live outside a standard table-backed resource.
23
23
 
24
24
  ## How It Works
25
25
 
26
- 1. **Import `Resource` from the `harper` package**: Always import explicitly rather than relying on globals.
26
+ 1. **Import `Resource` from `harper`**: Pull in the base class before extending it.
27
27
 
28
28
  ```javascript
29
29
  import { tables, Resource } from 'harper';
30
30
  ```
31
31
 
32
- CommonJS alternative:
32
+ CommonJS is also supported:
33
33
 
34
34
  ```javascript
35
35
  const { tables, Resource } = require('harper');
36
36
  ```
37
37
 
38
- 2. **Define a class that `extends Resource`**: Use `export class` so Harper exposes it as an endpoint. Implement HTTP methods as `static` methods on the class.
38
+ 2. **Define a class that `extends Resource`**: Declare HTTP handler methods as `static` methods matching the HTTP verb (`get`, `put`, `post`, etc.). Each method receives a `target` object representing the request.
39
39
 
40
40
  ```javascript
41
41
  export class CustomEndpoint extends Resource {
@@ -47,7 +47,7 @@ Apply this rule when you need to create custom HTTP endpoints, wrap external API
47
47
  }
48
48
  ```
49
49
 
50
- 3. **Use `static` async methods to call external services**: Each HTTP verb maps to a `static` method of the same lowercase name.
50
+ 3. **Wrap external APIs** by making the `static` methods `async` and using `fetch` or any other async call inside them.
51
51
 
52
52
  ```javascript
53
53
  export class MyExternalData extends Resource {
@@ -63,13 +63,16 @@ Apply this rule when you need to create custom HTTP endpoints, wrap external API
63
63
  });
64
64
  }
65
65
  }
66
+
67
+ // Use as a cache source for a local table
68
+ tables.MyCache.sourcedFrom(MyExternalData);
66
69
  ```
67
70
 
68
- 4. **Control the URL by choosing the export form**: The shape of the export determines the resulting URL path.
71
+ 4. **Control the URL by choosing an export form**: The shape of the export determines the resulting endpoint URL.
69
72
 
70
73
  | Export form | URL | Notes |
71
74
  | ------------------------------------------- | --------------- | --------------------------------------------------------------- |
72
- | `export class Foo extends Resource {}` | `/Foo/` | Class name becomes the path segment; case-sensitive. |
75
+ | `export class Foo extends Resource {}` | `/Foo/` | Class name becomes the path segment. Case-sensitive. |
73
76
  | `export const Bar = { Foo };` | `/Bar/Foo/` | Nest under an object to add a path prefix. |
74
77
  | `export const bar = { 'foo-baz': Foo };` | `/bar/foo-baz/` | Use object keys for lowercase, hyphens, or non-identifier URLs. |
75
78
  | `export { Foo as '/widget/:id' }` | `/widget/:id` | Rename the export to set the path directly. |
@@ -78,7 +81,7 @@ Apply this rule when you need to create custom HTTP endpoints, wrap external API
78
81
 
79
82
  URL path matching is case-sensitive — `/Foo/` and `/foo/` are different endpoints.
80
83
 
81
- 5. **Declare dynamic path segments with `static path`**: Use `:name` for a single segment and `*name` as a catch-all. Matched values are bound onto `target.<name>`.
84
+ 5. **Declare dynamic path segments** using `static path` on the class. Use `:name` for a single segment and `*name` as a catch-all for the rest of the path. Matched values are bound onto `target.<name>`.
82
85
 
83
86
  ```javascript
84
87
  export class Widget extends Resource {
@@ -98,26 +101,36 @@ Apply this rule when you need to create custom HTTP endpoints, wrap external API
98
101
  }
99
102
  ```
100
103
 
101
- - A leading `/` in `static path` makes the path root-relative (top-level), independent of the file's location.
102
- - A leading `./` or bare name resolves relative to the component directory.
103
- - A bare `*` (no name) binds under `target.wildcard`. A wildcard must be the final segment.
104
+ - A bare `*` (no name) binds under `target.wildcard`.
105
+ - A wildcard must be the final segment of the path.
106
+ - A leading `/` makes the path root-relative (top-level), independent of the file's location.
107
+ - A leading `./` or a bare name resolves relative to the component directory.
104
108
  - `static path` takes precedence over the export name.
105
- - Exact and static paths always win over parameterized ones. Among parameterized routes, more specific paths win: a literal segment beats `:param`, which beats `*`, compared left to right.
106
109
 
107
- 6. **Register programmatically when the path is dynamic**: Use `server.resources.set(` with a path string and the resource class.
110
+ 6. **Understand resolution order**: Exact and static paths always win over parameterized ones. Among parameterized routes, more specific paths win: a literal segment beats a `:param`, which beats a `*` wildcard, compared left to right.
108
111
 
112
+ 7. **Register programmatically** using `server.resources.set(` when the path must be determined at runtime rather than statically.
109
113
  ```javascript
110
114
  server.resources.set('my-path', Foo);
111
115
  ```
112
116
 
113
- 7. **Optionally use a resource as a cache source for a local table**: Call `sourcedFrom` on the target table.
114
- ```javascript
115
- tables.MyCache.sourcedFrom(MyExternalData);
116
- ```
117
-
118
117
  ## Examples
119
118
 
120
- **Custom endpoint with external API wrapping:**
119
+ **Custom endpoint with a fixed path:**
120
+
121
+ ```javascript
122
+ import { Resource } from 'harper';
123
+
124
+ export class CustomEndpoint extends Resource {
125
+ static get(target) {
126
+ return {
127
+ data: doSomething(),
128
+ };
129
+ }
130
+ }
131
+ ```
132
+
133
+ **External API wrapper used as a cache source:**
121
134
 
122
135
  ```javascript
123
136
  import { tables, Resource } from 'harper';
@@ -136,7 +149,6 @@ export class MyExternalData extends Resource {
136
149
  }
137
150
  }
138
151
 
139
- // Use as a cache source for a local table
140
152
  tables.MyCache.sourcedFrom(MyExternalData);
141
153
  ```
142
154
 
@@ -146,39 +158,22 @@ tables.MyCache.sourcedFrom(MyExternalData);
146
158
  import { Resource } from 'harper';
147
159
 
148
160
  export class Widget extends Resource {
149
- // GET /widget/10/action/jump -> target.id === '10', target.action === 'jump'
150
161
  static path = '/widget/:id/action/:action';
151
162
  static get(target) {
152
163
  return { id: target.id, action: target.action };
153
164
  }
154
165
  }
155
-
156
- export class Files extends Resource {
157
- // GET /files/a/b/c.txt -> target.rest === 'a/b/c.txt'
158
- static path = '/files/*rest';
159
- static get(target) {
160
- return { path: target.rest };
161
- }
162
- }
163
166
  ```
164
167
 
165
168
  **Programmatic registration:**
166
169
 
167
170
  ```javascript
168
- import { Resource } from 'harper';
169
-
170
- export class Foo extends Resource {
171
- static get(target) {
172
- return { ok: true };
173
- }
174
- }
175
-
176
171
  server.resources.set('my-path', Foo);
177
172
  ```
178
173
 
179
174
  ## Notes
180
175
 
181
- - Avoid conflicting exports between the schema and the JavaScript implementation when a resource `extends` an existing table.
182
- - Parameterized routes appear in the generated OpenAPI document as templated paths (e.g. `/widget/{id}/action/{action}`) and in MCP `resources/templates/list` as `{param}` URI templates.
176
+ - Do not create conflicting exports between a schema definition and a JavaScript implementation when a resource extends an existing table.
177
+ - Parameterized routes surface in the generated OpenAPI document as templated paths (e.g., `/widget/{id}/action/{action}`) and in MCP `resources/templates/list` as `{param}` URI templates.
183
178
  - When bundling for SSR with a tool like Vite, keep `harper` external so it resolves to the runtime: `ssr: { external: ['harper'] }`.
184
- - For components in their own directory, run `npm link harper` to ensure typings match the running installation.
179
+ - Run `npm link harper` in a component's own directory to ensure typings match the running installation. All installed components have `harper` automatically linked.
@@ -6,23 +6,23 @@ metadata:
6
6
  sources:
7
7
  - reference/v5/database/schema.md#Relationships
8
8
  - reference/v5/rest/querying.md#Relationships and Joins
9
- sourceCommit: bea4e62cb7efd809bb67e00cbda01a410c1177b1
10
- inputHash: 58ffc789fa71ffe6
9
+ sourceCommit: 0a29827da61afe7fff40ee8de87e1d4c2c286bea
10
+ inputHash: 0e622617a8b5c196
11
11
  ---
12
12
 
13
13
  # Defining Relationships Between Tables in Harper
14
14
 
15
- Instructions for the agent to define and query relationships between Harper tables using the `@relationship` directive in GraphQL schemas.
15
+ Instructions for the agent to follow when defining and querying relationships between tables in Harper using the `@relationship` directive.
16
16
 
17
17
  **Instead of:** ORM relations and join tables (Prisma, Drizzle, Sequelize). Use this rule rather than adding that service. See `harper-architecture`.
18
18
 
19
19
  ## When to Use
20
20
 
21
- Apply this rule when writing Harper schemas that require join queries across tables, or when query results must include related records as nested properties. Use it whenever a foreign key exists in one table that references another, or when modeling one-to-many, many-to-one, or many-to-many associations.
21
+ Apply this rule when adding foreign-key relationships between schema tables, enabling join queries, or selecting nested related records in query results. Use it any time a schema type needs to reference records in another table via a `@relationship` directive.
22
22
 
23
23
  ## How It Works
24
24
 
25
- 1. **Declare a many-to-one relationship with `from`**: Place `@relationship(from: attribute)` on a field when the foreign key lives in the current table and references the primary key of the target table. The result type is a single object.
25
+ 1. **Use `@relationship(from: attribute)` for many-to-one or many-to-many**: Place this on the field whose table holds the foreign key. The `from` argument names the attribute in this table that stores the foreign key referencing the target table's primary key.
26
26
 
27
27
  ```graphql
28
28
  type RealityShow @table @export {
@@ -38,7 +38,17 @@ Apply this rule when writing Harper schemas that require join queries across tab
38
38
  }
39
39
  ```
40
40
 
41
- 2. **Declare a one-to-many relationship with `to`**: Place `@relationship(to: attribute)` on a field when the foreign key lives in the target table and references the primary key of the current table. The result type **must** be an array.
41
+ If the foreign key attribute is an array, the relationship becomes many-to-many:
42
+
43
+ ```graphql
44
+ type RealityShow @table @export {
45
+ id: Long @primaryKey
46
+ networkIds: [Long] @indexed
47
+ networks: [Network] @relationship(from: networkIds)
48
+ }
49
+ ```
50
+
51
+ 2. **Use `@relationship(to: attribute)` for one-to-many or many-to-many**: Place this on the field whose table holds the primary key. The `to` argument names the attribute in the _target_ table that stores the foreign key. The result type must be an array.
42
52
 
43
53
  ```graphql
44
54
  type Network @table @export {
@@ -48,14 +58,14 @@ Apply this rule when writing Harper schemas that require join queries across tab
48
58
  }
49
59
  ```
50
60
 
51
- 3. **Declare a foreign-key-to-foreign-key relationship with `@relationship(from: attribute, to: attribute)`**: Specify both `from` and `to` when neither side uses the primary key. Harper resolves the relationship by searching the target table's `to` attribute for matches using the current record's `from` attribute value. The result type must be an array.
61
+ 3. **Use `@relationship(from: attribute, to: attribute)` for foreign-key-to-foreign-key joins**: Specify both `from` and `to` when neither side uses the primary key. The result type must be an array. Harper resolves the relationship by searching the target table's `to` attribute for matches using this record's `from` attribute value.
52
62
 
53
63
  ```graphql
54
64
  type OrderItem @table @export {
55
65
  id: Long @primaryKey
56
66
  orderId: Long @indexed
57
67
  productSku: Long @indexed
58
- products: [Product] @relationship(from: productSku, to: sku) # matches products by sku, not primary key
68
+ products: [Product] @relationship(from: productSku, to: sku)
59
69
  }
60
70
 
61
71
  type Product @table @export {
@@ -65,17 +75,7 @@ Apply this rule when writing Harper schemas that require join queries across tab
65
75
  }
66
76
  ```
67
77
 
68
- 4. **Declare a many-to-many relationship using an array foreign key with `from`**: When the foreign key field is an array, `@relationship(from: attribute)` establishes a many-to-many relationship. The result type must be an array.
69
-
70
- ```graphql
71
- type RealityShow @table @export {
72
- id: Long @primaryKey
73
- networkIds: [Long] @indexed
74
- networks: [Network] @relationship(from: networkIds)
75
- }
76
- ```
77
-
78
- 5. **Query across relationships using dot-syntax**: Filter records by related table attributes using dot-chained attribute names. This behaves as an INNER JOIN — only parents with a qualifying related record are returned.
78
+ 4. **Query across relationships using dot-syntax**: Filter by related table attributes using dot-chained paths. This behaves as an INNER JOIN — only parents with a matching related record are returned.
79
79
 
80
80
  ```
81
81
  GET /RealityShow?network.name=Bravo
@@ -83,7 +83,7 @@ Apply this rule when writing Harper schemas that require join queries across tab
83
83
  GET /Brand/?products.name=Keyboard
84
84
  ```
85
85
 
86
- 6. **Include relationship fields in results using `select()`**: Relationship attributes are not included by default. Use `select()` to project them, optionally with a nested field list using `{}`.
86
+ 5. **Include relationship fields in results using `select()`**: Relationship attributes are not included by default. Use `select()` to project them. Selecting a relationship without an outer dot-syntax filter behaves as a LEFT JOIN.
87
87
 
88
88
  ```
89
89
  GET /Product/?brand.name=Microsoft&select(name,brand)
@@ -91,15 +91,7 @@ Apply this rule when writing Harper schemas that require join queries across tab
91
91
  GET /Product/?name=Keyboard&select(name,brand{name,id})
92
92
  ```
93
93
 
94
- Selecting a relationship without an outer dot-syntax filter on it behaves as a LEFT JOIN: parents remain even when there are no related records.
95
-
96
- 7. **Filter and page nested relationship results using `[]` inside `select()`**: Apply conditions, sort, and pagination to each parent's related records by placing them inside square brackets in the `select()` expression.
97
-
98
- ```
99
- GET /Brand/?select(id,name,products[price=ge=number:30&sort(price)&limit(1)&select(id,name,price)])
100
- ```
101
-
102
- An outer relationship filter (e.g., `products.price=ge=number:30`) removes parents without a qualifying child **and** narrows the nested candidates. A filter inside `products[...]` only narrows projected children without removing their parent.
94
+ 6. **Apply conditions, sort, and pagination to nested related records using bracket syntax inside `select()`**: Use square brackets after the relationship name inside `select()` to filter, sort, and page each parent's related records independently.
103
95
 
104
96
  | Nested option | Behavior |
105
97
  | ------------------ | -------------------------------------------------------------------------- |
@@ -109,9 +101,27 @@ Apply this rule when writing Harper schemas that require join queries across tab
109
101
  | `limit(start,end)` | Skip `start` eligible children and return at most `end - start`. |
110
102
  | `select(id,price)` | Project fields from returned children; omit to return whole child records. |
111
103
 
104
+ Invalid `limit()` bounds (negative or fractional values) return HTTP 400. `limit(0)` returns no children without reading them.
105
+
106
+ 7. **Use bracket syntax on the relationship name in the query string to require one related record to meet multiple conditions**: This is distinct from separate `&`-joined conditions, which may be satisfied by different related records.
107
+
108
+ ```
109
+ GET /Brand/?products[name=Keyboard&price=ge=30]
110
+ ```
111
+
112
+ Inside brackets, name attributes of the related table directly (e.g., `price`, not `products.price`). Values convert to the attribute's schema type, so `price=ge=30` needs no `number:` prefix inside brackets.
113
+
114
+ 8. **Combine OR filters with child sorting and pagination**: Group OR conditions inside the relationship selection with `[condition1|condition2]`, then append `sort()`, `limit()`, and `select()` with `&`.
115
+
116
+ ```
117
+ GET /Brand/?sort(name,id)&limit(0,20)&select(id,name,products[[price=lt=number:30|price=ge=number:60]&sort(-price,id)&limit(1,2)&select(id,name,price)])
118
+ ```
119
+
120
+ 9. **Index foreign key and filter fields**: Keep relationship lookup fields and outer filter fields indexed. The `from` or `to` attribute referenced in `@relationship` should carry `@indexed`.
121
+
112
122
  ## Examples
113
123
 
114
- ### Schema with bidirectional relationships
124
+ ### Many-to-one with join query
115
125
 
116
126
  ```graphql
117
127
  type Product @table @export {
@@ -128,7 +138,12 @@ type Brand @table @export {
128
138
  }
129
139
  ```
130
140
 
131
- ### Many-to-many without a junction table
141
+ ```
142
+ GET /Product/?brand.name=Microsoft&select(name,brand{name,id})
143
+ GET /Brand/?products.name=Keyboard
144
+ ```
145
+
146
+ ### Many-to-many with array foreign key
132
147
 
133
148
  ```graphql
134
149
  type Product @table @export {
@@ -143,11 +158,7 @@ type Product @table @export {
143
158
  GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
144
159
  ```
145
160
 
146
- The array order of `resellerIds` is preserved when resolving the relationship.
147
-
148
- ### Nested filtering and pagination scenarios
149
-
150
- Schema for the following examples:
161
+ ### Nested filtering and pagination
151
162
 
152
163
  ```graphql
153
164
  type Brand @table @export {
@@ -164,42 +175,68 @@ type Product @table @export {
164
175
  }
165
176
  ```
166
177
 
167
- **Keep every brand; show its cheapest product costing at least 30** (LEFT JOIN behavior — Budget Basics returns with an empty product list):
178
+ Keep every brand; show its cheapest product costing at least 30 (LEFT JOIN behavior — Budget Basics remains with an empty product list):
168
179
 
169
180
  ```
170
181
  GET /Brand/?select(id,name,products[price=ge=number:30&sort(price)&limit(1)&select(id,name,price)])
171
182
  ```
172
183
 
173
- **Return only qualifying brands; inherit the outer price filter** (INNER JOIN behavior — Budget Basics is removed):
184
+ Return only qualifying brands; inherit the outer price filter into nested results:
174
185
 
175
186
  ```
176
187
  GET /Brand/?products.price=ge=number:30&select(id,name,products[sort(price)&limit(1)&select(id,name,price)])
177
188
  ```
178
189
 
179
- **Page through each brand's qualifying products** (offset applies independently per brand):
190
+ Page through each brand's qualifying products (offset applies independently per brand):
180
191
 
181
192
  ```
182
193
  GET /Brand/?products.price=ge=number:30&select(id,name,products[sort(price)&limit(1,2)&select(id,name,price)])
183
194
  ```
184
195
 
185
- **Bound parent pages with stable sorting**:
196
+ Bound parent pages with stable sorting:
186
197
 
187
198
  ```
188
199
  GET /Brand/?products.price=ge=number:30&sort(name,id)&limit(0,20)&select(id,name,products[sort(price,id)&limit(1)&select(id,name,price)])
189
200
  ```
190
201
 
191
- **Combine OR filters with child sorting and pagination**:
202
+ ### Conditions through several relationships
192
203
 
204
+ ```graphql
205
+ type Company @table @export {
206
+ id: ID @primaryKey
207
+ departments: [Department] @relationship(to: "companyId")
208
+ }
209
+
210
+ type Department @table @export {
211
+ id: ID @primaryKey
212
+ companyId: ID @indexed
213
+ employees: [Employee] @relationship(to: "departmentId")
214
+ }
215
+
216
+ type Employee @table @export {
217
+ id: ID @primaryKey
218
+ departmentId: ID @indexed
219
+ tag: String @indexed
220
+ level: Int @indexed
221
+ }
193
222
  ```
194
- GET /Brand/?sort(name,id)&limit(0,20)&select(id,name,products[[price=lt=number:30|price=ge=number:60]&sort(-price,id)&limit(1,2)&select(id,name,price)])
195
- ```
223
+
224
+ | Query | Matches | Why |
225
+ | -------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------- |
226
+ | `departments.employees.tag=oncall&departments.employees.level=ge=number:3` | c1, c2, c3 | each condition may be met by a different department |
227
+ | `departments[employees.tag=oncall&employees.level=ge=number:3]` | c1, c2 | one department must meet both, possibly by different people |
228
+ | `departments[employees[tag=oncall&level=ge=3]]` | c2 | one employee must meet both |
229
+ | `departments.employees[tag=oncall&level=ge=3]` | c2 | same as the previous row |
196
230
 
197
231
  ## Notes
198
232
 
199
- - Index all foreign key fields (e.g., `brandId`, `price`) and outer filter fields to support efficient join queries.
200
- - Use a unique field as the final sort key (e.g., `sort(price,id)`) to ensure deterministic ordering when values are equal.
201
- - A nested `limit()` bounds children per parent, not the number of parents. Apply a separate outer `limit()` to bound the parent result set.
233
+ - `@relationship(from: ...)` — the foreign key is in **this** table; result type can be singular or array.
234
+ - `@relationship(to: ...)` — the foreign key is in the **target** table; result type **must** be an array.
235
+ - `@relationship(from: attribute, to: attribute)` — foreign-key-to-foreign-key join; result type **must** be an array.
236
+ - Selecting a relationship without an outer dot-syntax filter is a LEFT JOIN; parents without matching related records are retained.
237
+ - An outer filter joined with `&` (e.g., `products.price=ge=number:30`) removes parents without a qualifying related record **and** narrows the related records returned by `select()`. A condition inside an OR only decides which parents match; it does not narrow selected related records.
238
+ - A nested filter inside `select(...,products[...])` only narrows projected children; it does not remove the parent.
239
+ - Separate `&`-joined conditions on a one-to-many relationship may each be satisfied by a **different** related record. Use `relationship[cond1&cond2]` bracket syntax to require one related record to meet all conditions.
240
+ - Self-referential relationships (a table referencing itself) are supported for parent-child hierarchies.
202
241
  - Nested filters require a table-backed relationship. Filters on plain JSON projections or full-text predicates inside a relationship selection return HTTP 400.
203
- - Invalid `limit()` bounds (negative or fractional values) return HTTP 400. `limit(0)` returns no children without reading them.
204
- - A condition traversing another relationship qualifies the immediate child only; it does not narrow that child's projected descendants. Place grandchild constraints in the grandchild's own bracket selection.
205
- - Schemas can define self-referential relationships to enable parent-child hierarchies within a single table.
242
+ - Keep parent pages small using outer `limit()`; a nested `limit()` bounds children per parent, not the number of parents.