@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.
- package/.agents/skills/harper-best-practices/AGENTS.md +1260 -1113
- package/.agents/skills/harper-best-practices/rules/automatic-apis.md +118 -83
- package/.agents/skills/harper-best-practices/rules/checking-authentication.md +244 -256
- package/.agents/skills/harper-best-practices/rules/custom-resources.md +37 -42
- package/.agents/skills/harper-best-practices/rules/defining-relationships.md +86 -49
- package/.agents/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
- package/.agents/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
- package/.agents/skills/harper-best-practices/rules/load-env.md +27 -30
- package/.agents/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
- package/.agents/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
- package/.agents/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
- package/.agents/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
- package/.agents/skills/harper-best-practices/rules/vector-indexing.md +77 -68
- package/.agents/skills/harper-mcp/AGENTS.md +228 -155
- package/.agents/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
- package/.agents/skills/harper-mcp/rules/enabling-mcp.md +104 -92
- package/.agents/skills/harper-mcp/rules/rate-limiting.md +95 -28
- package/agent/skills/harper-best-practices/AGENTS.md +1260 -1113
- package/agent/skills/harper-best-practices/rules/automatic-apis.md +118 -83
- package/agent/skills/harper-best-practices/rules/checking-authentication.md +244 -256
- package/agent/skills/harper-best-practices/rules/custom-resources.md +37 -42
- package/agent/skills/harper-best-practices/rules/defining-relationships.md +86 -49
- package/agent/skills/harper-best-practices/rules/deploying-from-ci.md +163 -170
- package/agent/skills/harper-best-practices/rules/deploying-to-harper-fabric.md +128 -88
- package/agent/skills/harper-best-practices/rules/load-env.md +27 -30
- package/agent/skills/harper-best-practices/rules/programmatic-table-requests.md +184 -155
- package/agent/skills/harper-best-practices/rules/querying-rest-apis.md +146 -94
- package/agent/skills/harper-best-practices/rules/schema-design-tooling.md +60 -77
- package/agent/skills/harper-best-practices/rules/v5-upgrade.md +52 -63
- package/agent/skills/harper-best-practices/rules/vector-indexing.md +77 -68
- package/agent/skills/harper-mcp/AGENTS.md +228 -155
- package/agent/skills/harper-mcp/rules/custom-mcp-tools.md +35 -41
- package/agent/skills/harper-mcp/rules/enabling-mcp.md +104 -92
- package/agent/skills/harper-mcp/rules/rate-limiting.md +95 -28
- package/package.json +1 -1
- 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:
|
|
11
|
-
inputHash:
|
|
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
|
|
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
|
|
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
|
|
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`**:
|
|
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. **
|
|
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
|
|
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
|
|
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
|
|
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
|
|
102
|
-
- A
|
|
103
|
-
- A
|
|
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. **
|
|
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
|
|
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
|
-
-
|
|
182
|
-
- Parameterized routes
|
|
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
|
-
-
|
|
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:
|
|
10
|
-
inputHash:
|
|
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
|
|
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
|
|
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. **
|
|
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
|
-
|
|
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. **
|
|
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)
|
|
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. **
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
200
|
-
-
|
|
201
|
-
-
|
|
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
|
-
-
|
|
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.
|