@harperfast/template-vue-studio 1.13.6 → 1.14.0
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 +7 -7
|
@@ -5,8 +5,8 @@ metadata:
|
|
|
5
5
|
mode: generate
|
|
6
6
|
sources:
|
|
7
7
|
- reference/v5/database/schema.md#Vector Indexing
|
|
8
|
-
sourceCommit:
|
|
9
|
-
inputHash:
|
|
8
|
+
sourceCommit: 1b103f864df3a0d8444297c00e752c29c2e7e82b
|
|
9
|
+
inputHash: 8f9270223df41d20
|
|
10
10
|
---
|
|
11
11
|
|
|
12
12
|
# Vector Indexing
|
|
@@ -49,7 +49,7 @@ Apply this rule when adding a vector similarity search capability to a Harper ta
|
|
|
49
49
|
});
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
-
4. **Apply a function predicate
|
|
52
|
+
4. **Apply a function predicate** using `vectorFilter` (JavaScript API only) for predicates not expressible as conditions. The function receives each candidate record and must return a synchronous boolean. Records are frozen:
|
|
53
53
|
|
|
54
54
|
```javascript
|
|
55
55
|
let results = Document.search(
|
|
@@ -76,7 +76,7 @@ Apply this rule when adding a vector similarity search capability to a Harper ta
|
|
|
76
76
|
});
|
|
77
77
|
```
|
|
78
78
|
|
|
79
|
-
6. **Include computed distance in results
|
|
79
|
+
6. **Include computed distance** in results by adding `$distance` to `select`. Works with both `sort`-based ranking and threshold queries:
|
|
80
80
|
|
|
81
81
|
```javascript
|
|
82
82
|
let results = Document.search({
|
|
@@ -95,7 +95,10 @@ Apply this rule when adding a vector similarity search capability to a Harper ta
|
|
|
95
95
|
});
|
|
96
96
|
```
|
|
97
97
|
|
|
98
|
-
|
|
98
|
+
- `distance` — overrides the index distance function: `"cosine"`, `"euclidean"`, or `"dotProduct"`.
|
|
99
|
+
- `ef` — overrides the search exploration budget. Higher values improve recall at the cost of latency.
|
|
100
|
+
|
|
101
|
+
8. **Tune filtered traversal** when a `vectorFilter` is very selective. Filtered traversal is bounded by `ef * filterExpansion` nodes visited. Raise either knob to trade latency for recall:
|
|
99
102
|
|
|
100
103
|
```javascript
|
|
101
104
|
let results = Document.search(
|
|
@@ -108,96 +111,102 @@ Apply this rule when adding a vector similarity search capability to a Harper ta
|
|
|
108
111
|
);
|
|
109
112
|
```
|
|
110
113
|
|
|
111
|
-
9. **
|
|
112
|
-
|
|
113
|
-
```javascript
|
|
114
|
-
function canReadReport(record, context) {
|
|
115
|
-
const user = context.user;
|
|
116
|
-
if (user?.role?.permission?.super_user) return true;
|
|
117
|
-
return user?.username != null && record.ownerId != null && record.ownerId === user.username;
|
|
118
|
-
}
|
|
114
|
+
9. **Configure HNSW index parameters** in the schema directive. Use the parameter table below to choose values:
|
|
119
115
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
116
|
+
```graphql
|
|
117
|
+
type Document @table {
|
|
118
|
+
id: Long @primaryKey
|
|
119
|
+
textEmbeddings: [Float]
|
|
120
|
+
@indexed(type: "HNSW", distance: "euclidean", optimizeRouting: 0, efConstructionSearch: 100)
|
|
125
121
|
}
|
|
126
122
|
```
|
|
127
123
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
124
|
+
| Parameter | Default | Description |
|
|
125
|
+
| ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------ |
|
|
126
|
+
| `distance` | `"cosine"` | Distance function: `"cosine"`, `"euclidean"`, or `"dotProduct"` |
|
|
127
|
+
| `efConstruction` | `100` | Max nodes explored during index construction. Higher = better recall, lower = better performance |
|
|
128
|
+
| `M` | `16` | Preferred connections per graph layer |
|
|
129
|
+
| `optimizeRouting` | `0.5` | Heuristic aggressiveness for omitting redundant connections (0 = off, 1 = most aggressive) |
|
|
130
|
+
| `mL` | computed from `M` | Normalization factor for level generation |
|
|
131
|
+
| `efConstructionSearch` | auto-scaled | Max nodes explored during search. When unset, auto-scales with index size |
|
|
132
|
+
| `quantization` | — | `"int8"` stores vectors quantized to int8 |
|
|
133
|
+
| `filterExpansion` | `24` | Visit-budget multiplier for filtered search: visits at most `ef * filterExpansion` nodes |
|
|
131
134
|
|
|
132
|
-
|
|
133
|
-
| ---------------------- | ----------------- | ------------------------------------------------------------------------------------------------ |
|
|
134
|
-
| `distance` | `"cosine"` | Distance function: `"cosine"`, `"euclidean"`, or `"dotProduct"` |
|
|
135
|
-
| `efConstruction` | `100` | Max nodes explored during index construction. Higher = better recall, lower = better performance |
|
|
136
|
-
| `M` | `16` | Preferred connections per graph layer |
|
|
137
|
-
| `optimizeRouting` | `0.5` | Heuristic aggressiveness for omitting redundant connections (0 = off, 1 = most aggressive) |
|
|
138
|
-
| `mL` | computed from `M` | Normalization factor for level generation |
|
|
139
|
-
| `efConstructionSearch` | auto-scaled | Max nodes explored during search. When unset, auto-scales with index size |
|
|
140
|
-
| `quantization` | — | `"int8"` stores vectors quantized to int8 |
|
|
141
|
-
| `filterExpansion` | `24` | Visit-budget multiplier for filtered search: visits at most `ef * filterExpansion` nodes |
|
|
135
|
+
> Use `efConstructionSearch` (not `efSearchConstruction`). Changing `efConstructionSearch` on an existing index does not trigger a rebuild. Changing structural parameters (`distance`, `M`, `efConstruction`, `quantization`) does rebuild the index.
|
|
142
136
|
|
|
143
|
-
|
|
137
|
+
10. **Enable vector quantization** with `quantization: "int8"` to reduce index size and memory usage. Graph navigation uses quantized distances; nearest-neighbor `sort` queries are re-ranked against full-precision vectors for exact results:
|
|
144
138
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
139
|
+
```graphql
|
|
140
|
+
type Document @table {
|
|
141
|
+
id: Long @primaryKey
|
|
142
|
+
textEmbeddings: [Float] @indexed(type: "HNSW", quantization: "int8")
|
|
143
|
+
}
|
|
144
|
+
```
|
|
149
145
|
|
|
150
146
|
## Examples
|
|
151
147
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
```graphql
|
|
155
|
-
type Document @table {
|
|
156
|
-
id: Long @primaryKey
|
|
157
|
-
textEmbeddings: [Float]
|
|
158
|
-
@indexed(type: "HNSW", distance: "euclidean", optimizeRouting: 0, efConstructionSearch: 100)
|
|
159
|
-
}
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
**Index with int8 quantization:**
|
|
148
|
+
### Basic nearest-neighbor search
|
|
163
149
|
|
|
164
150
|
```graphql
|
|
165
151
|
type Document @table {
|
|
166
152
|
id: Long @primaryKey
|
|
167
|
-
textEmbeddings: [Float] @indexed(type: "HNSW"
|
|
153
|
+
textEmbeddings: [Float] @indexed(type: "HNSW")
|
|
168
154
|
}
|
|
169
155
|
```
|
|
170
156
|
|
|
171
|
-
**Nearest-neighbor search with distance included:**
|
|
172
|
-
|
|
173
157
|
```javascript
|
|
174
158
|
let results = Document.search({
|
|
175
|
-
select: ['name', '$distance'],
|
|
176
159
|
sort: { attribute: 'textEmbeddings', target: searchVector },
|
|
177
160
|
limit: 5,
|
|
178
161
|
});
|
|
179
162
|
```
|
|
180
163
|
|
|
181
|
-
|
|
164
|
+
### Filtered vector search with row-level access control
|
|
182
165
|
|
|
183
166
|
```javascript
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
)
|
|
167
|
+
function canReadReport(record, context) {
|
|
168
|
+
const user = context.user;
|
|
169
|
+
if (user?.role?.permission?.super_user) return true;
|
|
170
|
+
return user?.username != null && record.ownerId != null && record.ownerId === user.username;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
export class Reports extends tables.Reports {
|
|
174
|
+
get(target) {
|
|
175
|
+
const context = this.getContext();
|
|
176
|
+
if (target.isCollection) {
|
|
177
|
+
target.rowFilter = canReadReport;
|
|
178
|
+
} else if (!canReadReport(this, context)) {
|
|
179
|
+
return new Response(null, { status: 404 });
|
|
180
|
+
}
|
|
181
|
+
return super.get(target);
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
search(target) {
|
|
185
|
+
target.rowFilter = canReadReport;
|
|
186
|
+
return super.search(target);
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
subscribe(request) {
|
|
190
|
+
request.rowFilter = canReadReport;
|
|
191
|
+
return super.subscribe(request);
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### Custom HNSW parameters with cosine distance
|
|
197
|
+
|
|
198
|
+
```graphql
|
|
199
|
+
type Document @table {
|
|
200
|
+
id: Long @primaryKey
|
|
201
|
+
textEmbeddings: [Float]
|
|
202
|
+
@indexed(type: "HNSW", distance: "euclidean", optimizeRouting: 0, efConstructionSearch: 100)
|
|
203
|
+
}
|
|
192
204
|
```
|
|
193
205
|
|
|
194
206
|
## Notes
|
|
195
207
|
|
|
196
|
-
- `vectorFilter`
|
|
197
|
-
- `
|
|
198
|
-
- `
|
|
199
|
-
-
|
|
200
|
-
-
|
|
201
|
-
- The correct parameter name is `efConstruction` (seeds the construction budget) and `efConstructionSearch` (controls search budget). The name `efSearchConstruction` is a previous documentation error.
|
|
202
|
-
- When no `ef` is passed and `efConstructionSearch` (or `efConstruction`) is not explicitly set, the search budget auto-scales with index size.
|
|
203
|
-
- `cosine` is the default distance function when `distance` is not specified.
|
|
208
|
+
- `vectorFilter` is available from the JavaScript API only — it cannot be expressed in a REST query string. It must be synchronous, side-effect free, and fast. Verdicts are memoized per query.
|
|
209
|
+
- `rowFilter` is also JavaScript API only. It participates in HNSW traversal so callers receive the k nearest _matching_ records. It does not apply to direct primary-key `get` calls. Prefer indexed query conditions for predicates that can be expressed declaratively.
|
|
210
|
+
- When a query passes no `ef` and the index does not explicitly configure `efConstructionSearch` (or `efConstruction`), the search budget auto-scales with index size.
|
|
211
|
+
- Distance-threshold (`lt`/`le`) queries with `quantization: "int8"` filter on approximate distance, not re-ranked full-precision distance.
|
|
212
|
+
- `$distance` is available in both `sort`-based ranking and `conditions`-based threshold queries.
|