@harperfast/template-vue-studio 1.13.6 → 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
@@ -5,61 +5,61 @@ metadata:
5
5
  mode: generate
6
6
  sources:
7
7
  - reference/v5/rest/querying.md
8
- sourceCommit: 6c3e29dd9149201364b0d74642725c30f0305e3e
9
- inputHash: e034fdc191f2cdc0
8
+ sourceCommit: 0a29827da61afe7fff40ee8de87e1d4c2c286bea
9
+ inputHash: 1455773ffb363a28
10
10
  ---
11
11
 
12
- # Querying Harper REST APIs
12
+ # Querying REST APIs
13
13
 
14
- Instructions for the agent to filter, sort, select, and paginate records using Harper's URL-based query language on REST collection endpoints.
14
+ Instructions for the agent to filter, sort, select, and paginate Harper REST API collections using URL query parameters.
15
15
 
16
16
  ## When to Use
17
17
 
18
- Apply this rule whenever building or modifying REST requests against Harper collection paths that need attribute filtering, comparison operators, sorting, field selection, pagination, or relationship joins. This rule covers all query parameter construction for Harper's automatic REST APIs (see [automatic-apis.md](automatic-apis.md)).
18
+ Apply this rule when building or modifying HTTP requests against Harper REST collection endpoints that need attribute filtering, comparison operators, sorting, field selection, or pagination. Use it whenever constructing query strings for `GET` requests against table-backed resources exposed via `@export`. See [automatic-apis.md](automatic-apis.md) for how those endpoints are created.
19
19
 
20
20
  ## How It Works
21
21
 
22
- 1. **Filter by attribute**: Add query parameters matching attribute name to value. The queried attribute must be indexed.
22
+ 1. **Filter by attribute**: Add query parameters matching attribute names. The queried attribute must be indexed.
23
23
 
24
24
  ```
25
25
  GET /Product/?category=software
26
26
  GET /Product/?category=software&inStock=true
27
- GET /Product/?discount=null
28
27
  ```
29
28
 
30
- 2. **Apply comparison operators (FIQL syntax)**: Use FIQL operators in the query string for range and string comparisons.
31
-
32
- | Operator | Meaning |
33
- | -------------------- | -------------------------------------- |
34
- | `==` | Equal |
35
- | `=lt=` | Less than |
36
- | `=le=` | Less than or equal |
37
- | `=gt=` | Greater than |
38
- | `=ge=` | Greater than or equal |
39
- | `=ne=`, `!=` | Not equal |
40
- | `=ct=` | Contains (strings) |
41
- | `=sw=`, `==<value>*` | Starts with (strings) |
42
- | `=ew=` | Ends with (strings) |
43
- | `=`, `===` | Strict equality (no type conversion) |
44
- | `!==` | Strict inequality (no type conversion) |
29
+ 2. **Apply FIQL comparison operators**: Use FIQL syntax for range and equality comparisons.
30
+
31
+ | Operator | Meaning |
32
+ | ----------------------------------------- | --------------------------------------- |
33
+ | `==` | Equal |
34
+ | `=lt=` | Less than |
35
+ | `=le=` | Less than or equal |
36
+ | `=gt=` | Greater than |
37
+ | `=ge=` | Greater than or equal |
38
+ | `=ne=`, `!=` | Not equal |
39
+ | `=between=(low,high)`, `=gele=(low,high)` | At least `low` and at most `high` |
40
+ | `=gelt=(low,high)` | At least `low` and less than `high` |
41
+ | `=gtle=(low,high)` | Greater than `low` and at most `high` |
42
+ | `=gtlt=(low,high)` | Greater than `low` and less than `high` |
43
+ | `=ct=` | Contains (strings) |
44
+ | `=sw=`, `==<value>*` | Starts with (strings) |
45
+ | `=ew=` | Ends with (strings) |
46
+ | `=`, `===` | Strict equality (no type conversion) |
47
+ | `!==` | Strict inequality (no type conversion) |
45
48
 
46
49
  ```
47
50
  GET /Product/?price=gt=100
48
51
  GET /Product/?price=le=20
49
- GET /Product/?name==Keyboard*
50
52
  GET /Product/?category=software&price=gt=100&price=lt=200
51
- GET /Product/?listDate=gt=2017-03-08T09%3A30%3A00.000Z
53
+ GET /Product/?price=between=(100,200)
52
54
  ```
53
55
 
54
- 3. **Chain conditions for range queries**: Omit the attribute name on the second condition to apply it to the same attribute.
56
+ For date fields, URL-encode colons as `%3A`:
55
57
 
56
58
  ```
57
- GET /Product/?price=gt=100&lt=200
59
+ GET /Product/?listDate=gt=2017-03-08T09%3A30%3A00.000Z
58
60
  ```
59
61
 
60
- Chaining supports `gt`/`ge` combined with `lt`/`le` only.
61
-
62
- 4. **Apply type conversion**: For FIQL comparators, Harper converts values automatically. Use explicit type prefixes when needed.
62
+ 3. **Apply type conversion**: For FIQL comparators, Harper converts values automatically. Use explicit type prefixes when needed.
63
63
 
64
64
  | Syntax | Behavior |
65
65
  | ----------------------------------------- | ------------------------------------------- |
@@ -71,28 +71,44 @@ Apply this rule whenever building or modifying REST requests against Harper coll
71
71
  | `name==string:some%20text` | Keep as string with URL decode |
72
72
  | `name==date:2024-01-05T20%3A07%3A27.955Z` | Explicit Date conversion |
73
73
 
74
- For strict operators (`=`, `===`, `!==`), no automatic type conversion is applied.
74
+ If the attribute declares a type in the schema (e.g., `Float`), values are always converted to that type before searching. For strict operators (`=`, `===`, `!==`), no automatic type conversion is applied.
75
75
 
76
- 5. **Combine conditions with OR logic**: Use `|` instead of `&`.
76
+ 4. **Query for null values**: Use `=null` to match records storing `null`; use `=ne=null` to match records with a present, non-null value. A record that omits the attribute matches neither.
77
77
 
78
78
  ```
79
- GET /Product/?rating=5|featured=true
79
+ GET /Product/?discount=null
80
+ GET /Product/?discount=ne=null
80
81
  ```
81
82
 
82
- 6. **Group conditions**: Use parentheses or square brackets to control order of operations. Prefer square brackets when constructing queries from user input.
83
+ 5. **Understand null and omitted value behavior**: Comparators treat a null value and an omitted value the same way, except `==null`, which matches a stored `null` only.
84
+ - No range comparator (`=lt=`, `=le=`, `=gt=`, `=ge=`, `=between=`, etc.) matches a null or omitted value.
85
+ - `=ne=` with a non-null value matches null and omitted values.
86
+ - A `null` lower bound means no lower bound: `ge=null` and `gt=null` match every non-null value, and `between=(null,10)` returns the same records as `le=10`. A `null` upper bound: `lt=null` and `le=null` match nothing.
87
+ - Sorting puts null and omitted values first; `-` puts them last, with no guaranteed order between the two.
88
+
89
+ 6. **Chain range conditions**: Omit the attribute name on the second condition to apply it to the same attribute.
83
90
 
84
91
  ```
92
+ GET /Product/?price=gt=100&lt=200
93
+ ```
94
+
95
+ Chaining supports `gt`/`ge` combined with `lt`/`le` only.
96
+
97
+ 7. **Combine conditions with OR**: Use `|` instead of `&` for OR logic. Use parentheses or square brackets to group conditions.
98
+
99
+ ```
100
+ GET /Product/?rating=5|featured=true
85
101
  GET /Product/?rating=5|(price=gt=100&price=lt=200)
86
102
  GET /Product/?rating=5&[tag=fast|tag=scalable|tag=efficient]
87
103
  ```
88
104
 
89
- Construct from JavaScript:
105
+ Prefer square brackets when constructing queries from user input:
90
106
 
91
107
  ```javascript
92
108
  let url = `/Product/?rating=5&[${tags.map(encodeURIComponent).join('|')}]`;
93
109
  ```
94
110
 
95
- 7. **Select specific properties with `select()`**: Specify which properties to include in the response.
111
+ 8. **Select specific fields with `select()`**: Specify which properties to include in the response.
96
112
 
97
113
  | Syntax | Returns |
98
114
  | -------------------------------------- | ------------------------------------------------- |
@@ -108,32 +124,32 @@ Apply this rule whenever building or modifying REST requests against Harper coll
108
124
  GET /Product/?brand.name=Microsoft&select(name,brand{name})
109
125
  ```
110
126
 
111
- 8. **Limit results with `limit(end)` or `limit(start,end)`**: Return records in a zero-based window from `start` (inclusive) to `end` (exclusive). `limit(end)` starts at zero.
127
+ 9. **Limit results with `limit(end)` or `limit(start,end)`**: Return records in the zero-based window from `start` (inclusive) to `end` (exclusive). `limit(end)` starts at zero.
112
128
 
113
129
  ```
114
130
  GET /Product/?rating=gt=3&inStock=true&select(rating,name)&limit(20)
115
131
  GET /Product/?rating=gt=3&limit(10,30)
116
132
  ```
117
133
 
118
- 9. **Sort results with `sort(property)` or `sort(+property,-property,...)`**: Prefix `+` or no prefix = ascending; `-` = descending. Multiple properties break ties in order.
119
-
120
- ```
121
- GET /Product/?rating=gt=3&sort(+name)
122
- GET /Product/?sort(+rating,-price)
123
- ```
134
+ 10. **Sort results with `sort(property)` or `sort(+property,-property,...)`**: Prefix `+` or no prefix = ascending; `-` = descending. Multiple properties break ties in order.
124
135
 
125
- 10. **Request a total count for pagination**: Send a `Prefer` header on `GET` or `HEAD` requests. Counting requires a bounded `limit()` with page size no larger than 10,000 and window end no larger than 1,000,000.
136
+ ```
137
+ GET /Product/?rating=gt=3&sort(+name)
138
+ GET /Product/?sort(+rating,-price)
139
+ ```
126
140
 
127
- | `Prefer` value | Meaning |
128
- | ----------------- | --------------------------------------------------------------------------------------------- |
129
- | `count=exact` | Exact number of matching records. Off by default; requires `exactCount: true` in REST config. |
130
- | `count=estimated` | Fast approximate count. Does not require `exactCount`. |
141
+ 11. **Request total counts for pagination**: Send a `Prefer` header on `GET` or `HEAD` requests. Counting is opt-in; without the header, no count is computed. Counting requires a bounded `limit()` with page size (`end - start`, or `end` in the one-argument form) no larger than **10,000** and window end no larger than **1,000,000**.
131
142
 
132
143
  ```
133
144
  GET /Product/?category=software&limit(0,25)
134
145
  Prefer: count=exact
135
146
  ```
136
147
 
148
+ | `Prefer` value | Meaning |
149
+ | ----------------- | ----------------------------------------------------------- |
150
+ | `count=exact` | Exact count of matching records; scans the full matched set |
151
+ | `count=estimated` | Fast planner/table estimate; cheap and approximate |
152
+
137
153
  Response headers:
138
154
 
139
155
  ```
@@ -143,57 +159,93 @@ Apply this rule whenever building or modifying REST requests against Harper coll
143
159
  Preference-Applied: count=exact
144
160
  ```
145
161
 
146
- Enable exact counts in REST configuration:
162
+ | Header | Example | Description |
163
+ | -------------------- | ----------------- | ------------------------------------------------------------------------- |
164
+ | `Content-Range` | `items 0-24/1234` | 0-based inclusive range of records returned out of the total matching set |
165
+ | `Range-Unit` | `items` | The unit used by `Content-Range` |
166
+ | `Preference-Applied` | `count=exact` | The count mode the server applied |
167
+ - The response status for paginated results is always `200`; Harper does not use `206 Partial Content`. `Content-Range` is informational.
168
+ - Without `exactCount: true`, a `count=exact` request is served as an estimate (`Preference-Applied: count=estimated`). When the total cannot be produced, it is reported as `.../*` (e.g., `Content-Range: items 0-24/*`). `Preference-Applied` still echoes the requested mode, so an unavailable total (`.../*`) is distinct from a request that asked for no count.
169
+ - Exact counting is off by default. Enable it in REST configuration:
170
+ ```yaml
171
+ rest:
172
+ exactCount: true
173
+ ```
174
+ - When CORS is enabled, `Content-Range`, `Range-Unit`, and `Preference-Applied` are added to `Access-Control-Expose-Headers`.
175
+ - Full-text queries cannot provide an exact total count; `Prefer: count=exact` returns `Content-Range: items <range>/*` for full-text indexes.
176
+ - For JSON-array responses from full-text queries, check for a terminal error object shaped like `{ "error": "ErrorName: message" }` and treat the response as failed. A stream or JSON-parse error is also a failed page, not a record.
177
+
178
+ 12. **Use full-text operators**: For a `FullText` field carrying `@fullText`, use the field name as the query attribute with a full-text comparator.
147
179
 
148
- ```yaml
149
- rest:
150
- exactCount: true
180
+ ```
181
+ GET /Product/?catalogSearch=matches=waterproof%20trail
182
+ GET /Product/?catalogSearch=matches_phrase=trail%20running
183
+ GET /Product/?catalogSearch=matches_prefix=waterproof%20tra&limit(10)
151
184
  ```
152
185
 
153
- - The response status for paginated requests is always `200`; Harper does not use `206 Partial Content`.
154
- - A `HEAD` request with a `count` preference returns the count headers with no body.
155
- - When CORS is enabled, `Content-Range`, `Range-Unit`, and `Preference-Applied` are added to `Access-Control-Expose-Headers`.
156
- - Without `exactCount: true`, a `count=exact` request is served as an estimate. When the total cannot be produced, it is reported as `*` (e.g., `Content-Range: items 0-24/*`). `Preference-Applied` still echoes the requested mode, so an unavailable total (`.../*`) is distinct from a request that asked for no count.
186
+ Supported operators: `matches`, `matches_all`, `matches_phrase`, `matches_prefix`, `matches_fuzzy`, `matches_fuzzy_prefix`, plus a `not_` form of each. A negated full-text condition requires a non-negated condition on the same index. Repeat the parameter to provide both:
187
+
188
+ ```
189
+ GET /Product/?catalogSearch=matches=waterproof&catalogSearch=not_matches=leather
190
+ ```
191
+
192
+ Use operators like `=matches=`, `=matches_phrase=`, `=matches_prefix=`, and `=matches_fuzzy=` with the full-text field name. The REST URL syntax searches every source field in the index, so the caller must be allowed to read every source field.
157
193
 
158
- 11. **Query across relationships**: Use dot-syntax on attributes defined with `@relationship` in the schema.
194
+ 13. **Query across relationships**: Use dot-syntax to filter by related table attributes. Relationships must be defined with `@relationship` in the schema.
159
195
 
160
196
  ```
161
197
  GET /Product/?brand.name=Microsoft
162
- GET /Brand/?products.name=Keyboard
163
198
  GET /Product/?brand.name=Microsoft&select(name,brand{name})
164
199
  ```
165
200
 
166
- Selecting a relationship without an outer dot-syntax filter behaves as a LEFT JOIN. An outer filter such as `products.price=ge=number:30` removes parents without a qualifying product and also narrows the selected products.
201
+ Selecting a relationship without an outer dot-syntax filter behaves as a LEFT JOIN. An outer filter joined with `&` removes parents without a qualifying related record. An outer relationship filter narrows nested relationship results. A nested filter inside `select(...,products[...])` only narrows projected products; it does not remove a parent.
167
202
 
168
- 12. **Filter and page nested relationships**: Use square brackets inside `select()` to apply conditions, sort, and pagination to each parent's related records.
203
+ 14. **Apply conditions one related record must meet**: Use square brackets after the relationship name to require one related record to satisfy all enclosed conditions.
169
204
 
170
205
  ```
171
- GET /Brand/?select(id,name,products[price=ge=number:30&sort(price)&limit(1)&select(id,name,price)])
206
+ GET /Brand/?products[name=Cable&price=ge=30]
207
+ GET /Brand/?products[name=Keyboard&price=ge=30]
172
208
  ```
173
209
 
174
- An outer relationship filter also narrows that relationship's nested results — do not repeat the outer filter inside `[...]` unless you want to narrow further.
210
+ Inside the brackets, name attributes of the related table directly (e.g., `price`, not `products.price`). Conditions combine with `&`, `|`, and groups.
211
+
212
+ 15. **Filter and page nested relationships**: Use square brackets inside `select()` to apply conditions, sort, and pagination to each parent's related records.
213
+
214
+ ```
215
+ GET /Brand/?select(id,name,products[price=ge=number:30&sort(price)&limit(1)&select(id,name,price)])
216
+ ```
175
217
 
176
218
  | Nested option | Behavior |
177
219
  | ------------------ | --------------------------------------------------------------- |
178
- | Conditions | Qualify children; combine with `&` (AND), `\|` (OR), and groups |
220
+ | Conditions | Qualify children of the selected relationship |
179
221
  | `sort(price)` | Order eligible children before pagination |
180
222
  | `limit(end)` | Return at most `end` children per parent |
181
223
  | `limit(start,end)` | Skip `start` eligible children and return at most `end - start` |
182
224
  | `select(id,price)` | Project fields from returned children |
183
- - Invalid nested bounds (negative or fractional values) return HTTP 400. `limit(0)` returns no children without reading them.
225
+ - `limit(0)` returns no children without reading them. Invalid nested bounds (negative or fractional values) return HTTP 400.
226
+ - Nested filters require a table-backed relationship. Filters on plain JSON projections or full-text predicates inside a relationship selection return HTTP 400.
184
227
 
185
228
  ## Examples
186
229
 
187
- ### Range filter with sort and limit
230
+ ### Range filter with type conversion
188
231
 
189
232
  ```
190
- GET /Product/?category=software&price=gt=100&price=lt=200&sort(+price)&limit(0,25)
233
+ GET /Product/?price=gt=100&price=lt=200
234
+ GET /Product/?price=between=(100,200)
191
235
  ```
192
236
 
193
- ### Relationship join with nested selection
237
+ ### Null query
194
238
 
195
239
  ```
196
- GET /Product/?brand.name=Microsoft&select(name,brand{name,id})
240
+ GET /Product/?discount=null
241
+ GET /Product/?discount=ne=null
242
+ ```
243
+
244
+ ### Select with sort and limit
245
+
246
+ ```
247
+ GET /Product/?rating=gt=3&inStock=true&select(rating,name)&limit(20)
248
+ GET /Product/?sort(+rating,-price)
197
249
  ```
198
250
 
199
251
  ### Paginated request with exact count
@@ -203,41 +255,34 @@ GET /Product/?category=software&limit(0,25)
203
255
  Prefer: count=exact
204
256
  ```
205
257
 
206
- Response:
258
+ Response headers:
207
259
 
208
260
  ```
209
- HTTP/1.1 200 OK
210
261
  Content-Range: items 0-24/1234
211
262
  Range-Unit: items
212
263
  Preference-Applied: count=exact
213
264
  ```
214
265
 
215
- ### Nested relationship filter with OR, sort, and pagination
266
+ ### Relationship query with nested selection and pagination
216
267
 
217
268
  ```
218
- 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)])
269
+ GET /Brand/?products.price=ge=number:30&select(id,name,products[sort(price)&limit(1)&select(id,name,price)])
219
270
  ```
220
271
 
221
- ### Outer filter inheriting into nested selection
272
+ ### OR grouping with nested relationship filter and pagination
222
273
 
223
274
  ```
224
- GET /Brand/?products.price=ge=number:30&select(id,name,products[sort(price)&limit(1)&select(id,name,price)])
275
+ 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)])
225
276
  ```
226
277
 
227
- ### Many-to-many relationship query
228
-
229
- Schema:
278
+ ### Conditions through several relationship hops
230
279
 
231
- ```graphql
232
- type Product @table @export {
233
- id: Long @primaryKey
234
- name: String
235
- resellerIds: [Long] @indexed
236
- resellers: [Reseller] @relationship(from: "resellerIds")
237
- }
280
+ ```
281
+ GET /Company/?departments[employees[tag=oncall&level=ge=3]]
282
+ GET /Company/?departments.employees[tag=oncall&level=ge=3]
238
283
  ```
239
284
 
240
- Query:
285
+ ### Many-to-many relationship query
241
286
 
242
287
  ```
243
288
  GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
@@ -245,13 +290,20 @@ GET /Product/?resellers.name=Cool Shop&select(id,name,resellers{name,id})
245
290
 
246
291
  ## Notes
247
292
 
248
- - Queried attributes must be indexed for filtering to execute; only one attribute in a multi-attribute query needs to be indexed.
249
- - URL-encode colons in date values as `%3A` (e.g., `listDate=gt=2017-03-08T09%3A30%3A00.000Z`).
250
- - Square brackets are preferred over parentheses when constructing queries programmatically because standard URI encoding safely encodes `[` and `]`.
251
- - Brackets inside `select()` after a relationship name (e.g., `select(id,products[limit(1)])`) form a nested relationship query, not a grouping expression.
252
- - For full-text fields marked `@fullText`, use operators such as `=matches=`, `=matches_phrase=`, `=matches_prefix=`, `=matches_fuzzy=`, and their `=not_*=` negated forms. Full-text queries cannot provide an exact total count.
253
- - `limit(end)` and `limit(start,end)` inside a nested relationship selection apply per parent, not to the total result set.
254
- - Always add a unique field as the final sort key (e.g., `sort(name,id)`) to ensure deterministic ordering across pages.
255
- - Nested filters require a table-backed relationship; filters on plain JSON projections or full-text predicates inside a relationship selection return HTTP 400.
256
- - For streaming JSON-array responses, check for a terminal object shaped like `{ "error": "ErrorName: message" }` and treat the response as failed.
257
- - Access a specific property of a record using dot syntax on the record ID: `GET /MyTable/123.propertyName`. This only works for declared schema properties. The suffixes `.json`, `.cbor`, `.msgpack`, and `.csv` are reserved as content-type selectors and take precedence over a property of the same name.
293
+ - Only indexed attributes can lead a filter query; at least one attribute in a multi-attribute query must be indexed.
294
+ - Null indexing requires indexes created in v4.3.0 or later. Existing indexes must be removed and re-added to support `discount=null` queries.
295
+ - For strict operators (`=`, `===`, `!==`), no automatic type conversion is applied — the value is decoded as a URL-encoded string.
296
+ - No range comparator (`=lt=`, `=le=`, `=gt=`, `=ge=`, `=between=`, etc.) matches a null or omitted value.
297
+ - `=ne=` with a non-null value matches null and omitted values.
298
+ - A `null` lower bound means no lower bound: `ge=null` and `gt=null` match every non-null value, and `between=(null,10)` returns the same records as `le=10`. A `null` upper bound: `lt=null` and `le=null` match nothing.
299
+ - Sorting puts null and omitted values first; `-` puts them last, with no guaranteed order between the two.
300
+ - A `HEAD` request with a `count` preference returns count headers with no body.
301
+ - The response status for paginated results is always `200`; Harper does not use `206 Partial Content`. `Content-Range` is informational.
302
+ - Without `exactCount: true`, a `count=exact` request is served as an estimate (`Preference-Applied: count=estimated`). When the total cannot be produced, it is reported as `.../*` (e.g., `Content-Range: items 0-24/*`). `Preference-Applied` still echoes the requested mode, so an unavailable total (`.../*`) is distinct from a request that asked for no count.
303
+ - When CORS is enabled, `Content-Range`, `Range-Unit`, and `Preference-Applied` are added to `Access-Control-Expose-Headers`.
304
+ - Full-text queries cannot provide an exact total count; with exact counting enabled, `Prefer: count=exact` returns an unavailable total (`.../*`).
305
+ - For JSON-array responses from full-text queries, check for a terminal error object shaped like `{ "error": "ErrorName: message" }` and treat the response as failed. A stream or JSON-parse error is also a failed page, not a record.
306
+ - Access a specific property of a record by appending it with dot syntax to the record id: `GET /MyTable/123.propertyName`. This only works for declared properties. The suffixes `.json`, `.cbor`, `.msgpack`, and `.csv` are reserved as content-type selectors and take precedence over a property of the same name.
307
+ - Querying through a relationship requires read permission on the related table and each related attribute named in a condition; without it, Harper returns HTTP 403.
308
+ - Nested filters require a table-backed relationship. Filters on plain JSON projections or full-text predicates inside a relationship selection return HTTP 400.
309
+ - `limit(0)` returns no children without reading them. Invalid nested bounds (negative or fractional values) return HTTP 400.