@quickback-dev/cli 0.10.16 → 0.10.20
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/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +40 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.js +6 -6
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/skill/SKILL.md +142 -1051
- package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/dist/skill/docs/changelog.md +1192 -0
- package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
- package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/dist/skill/docs/compiler/config/agents.md +144 -0
- package/dist/skill/docs/compiler/config/auth.md +109 -0
- package/dist/skill/docs/compiler/config/bindings.md +176 -0
- package/dist/skill/docs/compiler/config/domains.md +149 -0
- package/dist/skill/docs/compiler/config/index.md +419 -0
- package/dist/skill/docs/compiler/config/output.md +338 -0
- package/dist/skill/docs/compiler/config/providers.md +248 -0
- package/dist/skill/docs/compiler/config/security.md +255 -0
- package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
- package/dist/skill/docs/compiler/config/variables.md +157 -0
- package/dist/skill/docs/compiler/definitions/access.md +445 -0
- package/dist/skill/docs/compiler/definitions/actions.md +884 -0
- package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
- package/dist/skill/docs/compiler/definitions/feature.md +164 -0
- package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
- package/dist/skill/docs/compiler/definitions/guards.md +241 -0
- package/dist/skill/docs/compiler/definitions/index.md +219 -0
- package/dist/skill/docs/compiler/definitions/masking.md +241 -0
- package/dist/skill/docs/compiler/definitions/read.md +220 -0
- package/dist/skill/docs/compiler/definitions/schema.md +697 -0
- package/dist/skill/docs/compiler/definitions/validation.md +35 -0
- package/dist/skill/docs/compiler/definitions/views.md +292 -0
- package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/dist/skill/docs/compiler/getting-started/index.md +192 -0
- package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
- package/dist/skill/docs/compiler/index.md +85 -0
- package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/dist/skill/docs/compiler/targets/index.md +47 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/dist/skill/docs/compiler/troubleshooting.md +120 -0
- package/dist/skill/docs/index.md +77 -0
- package/dist/skill/docs/stack/account-ui/customization.md +378 -0
- package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
- package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
- package/dist/skill/docs/stack/account-ui/index.md +147 -0
- package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
- package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/dist/skill/docs/stack/account-ui/worker.md +362 -0
- package/dist/skill/docs/stack/auth/api-keys.md +15 -0
- package/dist/skill/docs/stack/auth/device-auth.md +14 -0
- package/dist/skill/docs/stack/auth/index.md +64 -0
- package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
- package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/dist/skill/docs/stack/auth/security.md +455 -0
- package/dist/skill/docs/stack/auth/using-auth.md +39 -0
- package/dist/skill/docs/stack/cms/actions.md +199 -0
- package/dist/skill/docs/stack/cms/components.md +479 -0
- package/dist/skill/docs/stack/cms/connecting.md +199 -0
- package/dist/skill/docs/stack/cms/dashboard.md +39 -0
- package/dist/skill/docs/stack/cms/index.md +158 -0
- package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
- package/dist/skill/docs/stack/cms/pages.md +275 -0
- package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
- package/dist/skill/docs/stack/cms/schema-format.md +437 -0
- package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
- package/dist/skill/docs/stack/cms/security.md +203 -0
- package/dist/skill/docs/stack/cms/table-views.md +142 -0
- package/dist/skill/docs/stack/index.md +65 -0
- package/dist/skill/docs/stack/queues/handlers.md +317 -0
- package/dist/skill/docs/stack/queues/index.md +56 -0
- package/dist/skill/docs/stack/queues/using-queues.md +192 -0
- package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/dist/skill/docs/stack/realtime/index.md +67 -0
- package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/dist/skill/docs/stack/storage/index.md +17 -0
- package/dist/skill/docs/stack/storage/kv.md +204 -0
- package/dist/skill/docs/stack/storage/r2.md +232 -0
- package/dist/skill/docs/stack/storage/using-kv.md +70 -0
- package/dist/skill/docs/stack/storage/using-r2.md +55 -0
- package/dist/skill/docs/stack/vector/embeddings.md +554 -0
- package/dist/skill/docs/stack/vector/index.md +44 -0
- package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
- package/dist/skill/docs/stack/webhooks/index.md +36 -0
- package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
- package/package.json +1 -1
- package/src/skill/SKILL.md +142 -1051
- package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/src/skill/docs/changelog.md +1192 -0
- package/src/skill/docs/compiler/claude-code-skill.md +312 -0
- package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/src/skill/docs/compiler/config/agents.md +144 -0
- package/src/skill/docs/compiler/config/auth.md +109 -0
- package/src/skill/docs/compiler/config/bindings.md +176 -0
- package/src/skill/docs/compiler/config/domains.md +149 -0
- package/src/skill/docs/compiler/config/index.md +419 -0
- package/src/skill/docs/compiler/config/output.md +338 -0
- package/src/skill/docs/compiler/config/providers.md +248 -0
- package/src/skill/docs/compiler/config/security.md +255 -0
- package/src/skill/docs/compiler/config/single-tenant.md +128 -0
- package/src/skill/docs/compiler/config/variables.md +157 -0
- package/src/skill/docs/compiler/definitions/access.md +445 -0
- package/src/skill/docs/compiler/definitions/actions.md +884 -0
- package/src/skill/docs/compiler/definitions/concepts.md +52 -0
- package/src/skill/docs/compiler/definitions/feature.md +164 -0
- package/src/skill/docs/compiler/definitions/firewall.md +285 -0
- package/src/skill/docs/compiler/definitions/guards.md +241 -0
- package/src/skill/docs/compiler/definitions/index.md +219 -0
- package/src/skill/docs/compiler/definitions/masking.md +241 -0
- package/src/skill/docs/compiler/definitions/read.md +220 -0
- package/src/skill/docs/compiler/definitions/schema.md +697 -0
- package/src/skill/docs/compiler/definitions/validation.md +35 -0
- package/src/skill/docs/compiler/definitions/views.md +292 -0
- package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/src/skill/docs/compiler/getting-started/index.md +192 -0
- package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/src/skill/docs/compiler/getting-started/templates.md +111 -0
- package/src/skill/docs/compiler/index.md +85 -0
- package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/src/skill/docs/compiler/targets/index.md +47 -0
- package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/src/skill/docs/compiler/troubleshooting.md +120 -0
- package/src/skill/docs/index.md +77 -0
- package/src/skill/docs/stack/account-ui/customization.md +378 -0
- package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/src/skill/docs/stack/account-ui/features/index.md +291 -0
- package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/src/skill/docs/stack/account-ui/hooks.md +209 -0
- package/src/skill/docs/stack/account-ui/index.md +147 -0
- package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/src/skill/docs/stack/account-ui/standalone.md +149 -0
- package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/src/skill/docs/stack/account-ui/worker.md +362 -0
- package/src/skill/docs/stack/auth/api-keys.md +15 -0
- package/src/skill/docs/stack/auth/device-auth.md +14 -0
- package/src/skill/docs/stack/auth/index.md +64 -0
- package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/src/skill/docs/stack/auth/plugins/index.md +228 -0
- package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/src/skill/docs/stack/auth/security.md +455 -0
- package/src/skill/docs/stack/auth/using-auth.md +39 -0
- package/src/skill/docs/stack/cms/actions.md +199 -0
- package/src/skill/docs/stack/cms/components.md +479 -0
- package/src/skill/docs/stack/cms/connecting.md +199 -0
- package/src/skill/docs/stack/cms/dashboard.md +39 -0
- package/src/skill/docs/stack/cms/index.md +158 -0
- package/src/skill/docs/stack/cms/inline-editing.md +136 -0
- package/src/skill/docs/stack/cms/pages.md +275 -0
- package/src/skill/docs/stack/cms/record-layouts.md +151 -0
- package/src/skill/docs/stack/cms/schema-format.md +437 -0
- package/src/skill/docs/stack/cms/schema-registry.md +200 -0
- package/src/skill/docs/stack/cms/security.md +203 -0
- package/src/skill/docs/stack/cms/table-views.md +142 -0
- package/src/skill/docs/stack/index.md +65 -0
- package/src/skill/docs/stack/queues/handlers.md +317 -0
- package/src/skill/docs/stack/queues/index.md +56 -0
- package/src/skill/docs/stack/queues/using-queues.md +192 -0
- package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/src/skill/docs/stack/realtime/index.md +67 -0
- package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/src/skill/docs/stack/storage/index.md +17 -0
- package/src/skill/docs/stack/storage/kv.md +204 -0
- package/src/skill/docs/stack/storage/r2.md +232 -0
- package/src/skill/docs/stack/storage/using-kv.md +70 -0
- package/src/skill/docs/stack/storage/using-r2.md +55 -0
- package/src/skill/docs/stack/vector/embeddings.md +554 -0
- package/src/skill/docs/stack/vector/index.md +44 -0
- package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/src/skill/docs/stack/webhooks/inbound.md +186 -0
- package/src/skill/docs/stack/webhooks/index.md +36 -0
- package/src/skill/docs/stack/webhooks/outbound.md +281 -0
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Using KV
|
|
2
|
+
|
|
3
|
+
Cloudflare KV is used by the Quickback Stack for session storage, caching, and rate limiting.
|
|
4
|
+
|
|
5
|
+
## Session Storage
|
|
6
|
+
|
|
7
|
+
Better Auth stores sessions in KV by default for fast edge-based lookups. This is auto-configured by the compiler — no setup needed.
|
|
8
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
// How sessions work internally (auto-generated)
|
|
11
|
+
// On login: session stored in KV
|
|
12
|
+
await kv.put(`session:${sessionToken}`, JSON.stringify(sessionData), {
|
|
13
|
+
expirationTtl: 60 * 60 * 24 * 7, // 7 days
|
|
14
|
+
});
|
|
15
|
+
|
|
16
|
+
// On each request: session retrieved from KV
|
|
17
|
+
const session = await kv.get(`session:${sessionToken}`, "json");
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Sessions are automatically:
|
|
21
|
+
- **Created** on sign-in (email/password, passkey, magic link, etc.)
|
|
22
|
+
- **Validated** on every authenticated request via the `Authorization: Bearer <token>` header
|
|
23
|
+
- **Expired** after the configured TTL (default: 7 days)
|
|
24
|
+
- **Deleted** on sign-out
|
|
25
|
+
|
|
26
|
+
## Rate Limiting
|
|
27
|
+
|
|
28
|
+
KV powers the rate limiting middleware that protects auth endpoints:
|
|
29
|
+
|
|
30
|
+
```typescript
|
|
31
|
+
// Rate limit key structure (auto-generated)
|
|
32
|
+
// Key: ratelimit:{ip}:{endpoint}
|
|
33
|
+
// Value: request count
|
|
34
|
+
// TTL: rate limit window (e.g., 60 seconds)
|
|
35
|
+
const key = `ratelimit:${ip}:${endpoint}`;
|
|
36
|
+
const count = await kv.get(key);
|
|
37
|
+
if (count && parseInt(count) > limit) {
|
|
38
|
+
return c.json({ error: "Too many requests" }, 429);
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
See [Auth Security](/stack/auth/security) for rate limiting configuration options.
|
|
43
|
+
|
|
44
|
+
## Caching
|
|
45
|
+
|
|
46
|
+
You can use KV in custom action handlers for caching frequently accessed data:
|
|
47
|
+
|
|
48
|
+
```typescript
|
|
49
|
+
// In an action handler
|
|
50
|
+
execute: async ({ db, ctx }) => {
|
|
51
|
+
const kv = ctx.env.KV;
|
|
52
|
+
|
|
53
|
+
// Check cache first
|
|
54
|
+
const cached = await kv.get("expensive-query-result", "json");
|
|
55
|
+
if (cached) return cached;
|
|
56
|
+
|
|
57
|
+
// Compute and cache
|
|
58
|
+
const result = await db.select().from(analytics);
|
|
59
|
+
await kv.put("expensive-query-result", JSON.stringify(result), {
|
|
60
|
+
expirationTtl: 300, // 5 minutes
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
return result;
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## See Also
|
|
68
|
+
|
|
69
|
+
- [KV Setup](/stack/storage/kv) — Namespace creation and wrangler bindings
|
|
70
|
+
- [Auth Security](/stack/auth/security) — Rate limiting and cookie security configuration
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Using R2
|
|
2
|
+
|
|
3
|
+
Cloudflare R2 provides S3-compatible object storage for file uploads in the Quickback Stack.
|
|
4
|
+
|
|
5
|
+
## Upload Flow
|
|
6
|
+
|
|
7
|
+
The generated API provides a two-step upload process:
|
|
8
|
+
|
|
9
|
+
1. **Request a presigned URL** — Client calls the upload endpoint to get a time-limited URL
|
|
10
|
+
2. **Upload directly to R2** — Client uploads the file directly to R2 (bypasses your Worker)
|
|
11
|
+
3. **Store the reference** — The API records the file metadata in D1
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
# 1. Request presigned upload URL
|
|
15
|
+
curl -X POST https://api.example.com/api/v1/files/upload \
|
|
16
|
+
-H "Authorization: Bearer <token>" \
|
|
17
|
+
-H "Content-Type: application/json" \
|
|
18
|
+
-d '{"filename": "report.pdf", "contentType": "application/pdf"}'
|
|
19
|
+
|
|
20
|
+
# Response:
|
|
21
|
+
# { "uploadUrl": "https://bucket.r2.cloudflarestorage.com/...", "fileId": "file_abc123" }
|
|
22
|
+
|
|
23
|
+
# 2. Upload directly to R2 using the presigned URL
|
|
24
|
+
curl -X PUT "<uploadUrl>" \
|
|
25
|
+
-H "Content-Type: application/pdf" \
|
|
26
|
+
--data-binary @report.pdf
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Download Flow
|
|
30
|
+
|
|
31
|
+
Files are served through your Worker with security checks applied:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
# Download a file (auth + firewall enforced)
|
|
35
|
+
curl https://api.example.com/api/v1/files/file_abc123/download \
|
|
36
|
+
-H "Authorization: Bearer <token>"
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
The download endpoint:
|
|
40
|
+
1. Validates the user's session
|
|
41
|
+
2. Checks firewall — the file must belong to the user's organization
|
|
42
|
+
3. Checks access — the user must have the required role
|
|
43
|
+
4. Streams the file from R2
|
|
44
|
+
|
|
45
|
+
## Role-Based Access
|
|
46
|
+
|
|
47
|
+
File access respects the same security layers as your API:
|
|
48
|
+
|
|
49
|
+
- **Firewall** — Users can only access files belonging to their organization
|
|
50
|
+
- **Access** — Role-based download permissions
|
|
51
|
+
|
|
52
|
+
## See Also
|
|
53
|
+
|
|
54
|
+
- [R2 Setup](/stack/storage/r2) — Bucket creation, wrangler bindings, and configuration
|
|
55
|
+
- [Avatars](/stack/account-ui/features/avatars) — Avatar upload UI integration
|
|
@@ -0,0 +1,554 @@
|
|
|
1
|
+
# Automatic Embeddings
|
|
2
|
+
|
|
3
|
+
Quickback can automatically generate embeddings for your data using Cloudflare Queues and Workers AI. When configured, INSERT and UPDATE operations automatically enqueue embedding jobs that are processed asynchronously.
|
|
4
|
+
|
|
5
|
+
## Enabling Embeddings
|
|
6
|
+
|
|
7
|
+
Add an `embeddings` configuration to your resource definition:
|
|
8
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
// quickback/features/jobs/jobs.ts
|
|
11
|
+
import { defineTable } from "@quickback/compiler";
|
|
12
|
+
|
|
13
|
+
export default defineTable(jobs, {
|
|
14
|
+
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
15
|
+
|
|
16
|
+
embeddings: {
|
|
17
|
+
fields: ['description'], // Fields to concatenate and embed
|
|
18
|
+
model: '@cf/baai/bge-base-en-v1.5', // Embedding model (optional)
|
|
19
|
+
onInsert: true, // Auto-embed on create (default: true)
|
|
20
|
+
onUpdate: ['description'], // Re-embed when these fields change
|
|
21
|
+
embeddingColumn: 'embedding', // Column to store embedding
|
|
22
|
+
metadata: ['department'], // Metadata for Vectorize index
|
|
23
|
+
},
|
|
24
|
+
|
|
25
|
+
crud: {
|
|
26
|
+
create: { access: { roles: ['recruiter'] } },
|
|
27
|
+
update: { access: { roles: ['recruiter'] } },
|
|
28
|
+
},
|
|
29
|
+
});
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Configuration Options
|
|
33
|
+
|
|
34
|
+
| Option | Type | Default | Description |
|
|
35
|
+
|--------|------|---------|-------------|
|
|
36
|
+
| `fields` | `string[]` | **Required** | Fields to concatenate and embed |
|
|
37
|
+
| `model` | `string` | `'@cf/baai/bge-base-en-v1.5'` | Workers AI embedding model |
|
|
38
|
+
| `onInsert` | `boolean` | `true` | Embed on INSERT operations |
|
|
39
|
+
| `onUpdate` | `boolean \| string[]` | `true` | Embed on UPDATE; array limits to specific fields |
|
|
40
|
+
| `embeddingColumn` | `string` | `'embedding'` | Column to store the embedding vector |
|
|
41
|
+
| `separator` | `string` | `' '` | Separator for joining multiple fields |
|
|
42
|
+
| `metadata` | `string[]` | `[]` | Fields to include in Vectorize metadata |
|
|
43
|
+
|
|
44
|
+
### onUpdate Options
|
|
45
|
+
|
|
46
|
+
```typescript
|
|
47
|
+
// Always re-embed on any update
|
|
48
|
+
onUpdate: true
|
|
49
|
+
|
|
50
|
+
// Never re-embed on update
|
|
51
|
+
onUpdate: false
|
|
52
|
+
|
|
53
|
+
// Only re-embed when specific fields change
|
|
54
|
+
onUpdate: ['description', 'title']
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## How It Works
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
61
|
+
│ Main API Worker │
|
|
62
|
+
│ │
|
|
63
|
+
│ ┌─────────────────────┐ ┌────────────────────┐ │
|
|
64
|
+
│ │ POST /jobs │ │ Queue Consumer │ │
|
|
65
|
+
│ │ │ │ │ │
|
|
66
|
+
│ │ 1. Auth middleware │ │ 1. Workers AI │ │
|
|
67
|
+
│ │ 2. Firewall │ │ embed() │ │
|
|
68
|
+
│ │ 3. Guards │ │ 2. D1 update() │ │
|
|
69
|
+
│ │ 4. Insert to D1 │ │ 3. Vectorize │ │
|
|
70
|
+
│ │ 5. Enqueue job ─────┼───▶│ upsert() │ │
|
|
71
|
+
│ └─────────────────────┘ └────────────────────┘ │
|
|
72
|
+
│ ▲ │
|
|
73
|
+
│ ┌─────────────────┴──────────────────┐ │
|
|
74
|
+
│ │ EMBEDDINGS_QUEUE │ │
|
|
75
|
+
│ └────────────────────────────────────┘ │
|
|
76
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
1. **API Request** - POST/PATCH arrives and passes through auth, firewall, guards
|
|
80
|
+
2. **Database Insert** - Record is created/updated in D1
|
|
81
|
+
3. **Enqueue Job** - Embedding job is sent to Cloudflare Queue
|
|
82
|
+
4. **Queue Consumer** - Processes job asynchronously:
|
|
83
|
+
- Calls Workers AI to generate embedding
|
|
84
|
+
- Updates D1 with embedding vector
|
|
85
|
+
- Optionally upserts to Vectorize index
|
|
86
|
+
|
|
87
|
+
## Security Model
|
|
88
|
+
|
|
89
|
+
**Security is enforced at enqueue time, not consume time:**
|
|
90
|
+
|
|
91
|
+
- Jobs are only enqueued after passing all security checks (auth, firewall, guards)
|
|
92
|
+
- The queue consumer is an internal process that executes pre-validated jobs
|
|
93
|
+
- If a user can't create a job posting, they can't trigger an embedding job
|
|
94
|
+
|
|
95
|
+
## Generic Embeddings API
|
|
96
|
+
|
|
97
|
+
In addition to automatic embeddings on CRUD operations, Quickback generates a generic embeddings API endpoint that allows you to trigger embeddings on arbitrary content.
|
|
98
|
+
|
|
99
|
+
### POST /api/v1/embeddings
|
|
100
|
+
|
|
101
|
+
Generate an embedding for any text content:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
curl -X POST https://your-api.workers.dev/api/v1/embeddings \
|
|
105
|
+
-H "Content-Type: application/json" \
|
|
106
|
+
-H "Cookie: better-auth.session_token=..." \
|
|
107
|
+
-d '{
|
|
108
|
+
"content": "Text to embed",
|
|
109
|
+
"model": "@cf/baai/bge-base-en-v1.5",
|
|
110
|
+
"table": "jobs",
|
|
111
|
+
"id": "job_123"
|
|
112
|
+
}'
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
#### Request Body
|
|
116
|
+
|
|
117
|
+
| Field | Type | Required | Description |
|
|
118
|
+
|-------|------|----------|-------------|
|
|
119
|
+
| `content` | `string` | Yes | Text to generate embedding for |
|
|
120
|
+
| `model` | `string` | No | Embedding model (defaults to table config or `@cf/baai/bge-base-en-v1.5`) |
|
|
121
|
+
| `table` | `string` | No | Table to store embedding back to |
|
|
122
|
+
| `id` | `string` | Conditional | Record ID to update (required if `table` is specified) |
|
|
123
|
+
|
|
124
|
+
#### Response
|
|
125
|
+
|
|
126
|
+
```json
|
|
127
|
+
{
|
|
128
|
+
"queued": true,
|
|
129
|
+
"jobId": "550e8400-e29b-41d4-a716-446655440000",
|
|
130
|
+
"table": "jobs",
|
|
131
|
+
"id": "job_123",
|
|
132
|
+
"model": "@cf/baai/bge-base-en-v1.5"
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### GET /api/v1/embeddings/tables
|
|
137
|
+
|
|
138
|
+
List tables that have embeddings configured:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
curl https://your-api.workers.dev/api/v1/embeddings/tables \
|
|
142
|
+
-H "Cookie: better-auth.session_token=..."
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Response:
|
|
146
|
+
|
|
147
|
+
```json
|
|
148
|
+
{
|
|
149
|
+
"tables": [
|
|
150
|
+
{
|
|
151
|
+
"name": "jobs",
|
|
152
|
+
"embeddingColumn": "embedding",
|
|
153
|
+
"model": "@cf/baai/bge-base-en-v1.5"
|
|
154
|
+
}
|
|
155
|
+
]
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### Authentication & Authorization
|
|
160
|
+
|
|
161
|
+
The generic embeddings API requires authentication and uses the `activeOrgId` from the user's context to enforce organization-level isolation. Embedding jobs are scoped to the user's current organization.
|
|
162
|
+
|
|
163
|
+
### Use Cases
|
|
164
|
+
|
|
165
|
+
The generic embeddings API is useful for:
|
|
166
|
+
|
|
167
|
+
- **Batch embedding**: Embed content without going through CRUD routes
|
|
168
|
+
- **Re-embedding**: Force re-generation of embeddings for existing records
|
|
169
|
+
- **Preview embeddings**: Test embedding generation before persisting
|
|
170
|
+
- **External content**: Embed content that doesn't fit your defined schemas
|
|
171
|
+
|
|
172
|
+
## Generated Files
|
|
173
|
+
|
|
174
|
+
When embeddings are configured, the compiler generates:
|
|
175
|
+
|
|
176
|
+
| File | Purpose |
|
|
177
|
+
|------|---------|
|
|
178
|
+
| `src/queue-consumer.ts` | Queue consumer handler for processing embedding jobs |
|
|
179
|
+
| `src/routes/embeddings.ts` | Generic embeddings API routes |
|
|
180
|
+
| `wrangler.toml` | Queue producer/consumer bindings, AI binding |
|
|
181
|
+
| `src/env.d.ts` | `EMBEDDINGS_QUEUE`, `AI` types |
|
|
182
|
+
| `src/index.ts` | Exports `queue` handler, mounts `/api/v1/embeddings` |
|
|
183
|
+
|
|
184
|
+
### wrangler.toml additions
|
|
185
|
+
|
|
186
|
+
```toml
|
|
187
|
+
# Embeddings Queue
|
|
188
|
+
[[queues.producers]]
|
|
189
|
+
queue = "your-app-embeddings-queue"
|
|
190
|
+
binding = "EMBEDDINGS_QUEUE"
|
|
191
|
+
|
|
192
|
+
[[queues.consumers]]
|
|
193
|
+
queue = "your-app-embeddings-queue"
|
|
194
|
+
max_batch_size = 10
|
|
195
|
+
max_batch_timeout = 30
|
|
196
|
+
max_retries = 3
|
|
197
|
+
|
|
198
|
+
# Workers AI
|
|
199
|
+
[ai]
|
|
200
|
+
binding = "AI"
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## Multiple Fields
|
|
204
|
+
|
|
205
|
+
Embed multiple fields by concatenating them:
|
|
206
|
+
|
|
207
|
+
```typescript
|
|
208
|
+
embeddings: {
|
|
209
|
+
fields: ['title', 'description', 'department'], // Joined with spaces by default
|
|
210
|
+
// ...
|
|
211
|
+
}
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Generated embedding text: `"${title} ${description} ${department}"`
|
|
215
|
+
|
|
216
|
+
### Custom Separator
|
|
217
|
+
|
|
218
|
+
Use `separator` to control how fields are joined. This is useful for sentence boundary detection:
|
|
219
|
+
|
|
220
|
+
```typescript
|
|
221
|
+
embeddings: {
|
|
222
|
+
fields: ['title', 'description'],
|
|
223
|
+
separator: '. ', // Join with period + space
|
|
224
|
+
// ...
|
|
225
|
+
}
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
Generated code: `[result[0].title, result[0].description].filter(Boolean).join('. ')`
|
|
229
|
+
|
|
230
|
+
The `filter(Boolean)` ensures null or empty fields are excluded cleanly — no trailing separator when a field is absent.
|
|
231
|
+
|
|
232
|
+
## Vectorize Integration
|
|
233
|
+
|
|
234
|
+
If you have a Vectorize index configured, embeddings are automatically upserted:
|
|
235
|
+
|
|
236
|
+
```typescript
|
|
237
|
+
// quickback.config.ts
|
|
238
|
+
providers: {
|
|
239
|
+
database: {
|
|
240
|
+
config: {
|
|
241
|
+
vectorizeIndexName: 'jobs-embeddings', // Your Vectorize index
|
|
242
|
+
vectorizeBinding: 'VECTORIZE',
|
|
243
|
+
},
|
|
244
|
+
},
|
|
245
|
+
},
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
The queue consumer will:
|
|
249
|
+
1. Generate the embedding via Workers AI
|
|
250
|
+
2. Store the vector in D1 (JSON string)
|
|
251
|
+
3. Upsert to Vectorize with metadata
|
|
252
|
+
|
|
253
|
+
### Vectorize Metadata
|
|
254
|
+
|
|
255
|
+
Include fields in Vectorize metadata for filtering:
|
|
256
|
+
|
|
257
|
+
```typescript
|
|
258
|
+
embeddings: {
|
|
259
|
+
fields: ['description'],
|
|
260
|
+
metadata: ['department', 'organizationId', 'status'],
|
|
261
|
+
}
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
Enables queries like:
|
|
265
|
+
```typescript
|
|
266
|
+
const results = await env.VECTORIZE.query(vector, {
|
|
267
|
+
topK: 10,
|
|
268
|
+
filter: { department: 'engineering' }
|
|
269
|
+
});
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
## Schema Requirements
|
|
273
|
+
|
|
274
|
+
Your schema must include the embedding column:
|
|
275
|
+
|
|
276
|
+
```typescript
|
|
277
|
+
// quickback/features/jobs/jobs.ts
|
|
278
|
+
import { feature, q } from "@quickback/compiler";
|
|
279
|
+
|
|
280
|
+
export default feature("jobs", {
|
|
281
|
+
columns: {
|
|
282
|
+
id: q.id(),
|
|
283
|
+
title: q.text().required(),
|
|
284
|
+
description: q.text().required(),
|
|
285
|
+
department: q.text().optional(),
|
|
286
|
+
status: q.text().required(),
|
|
287
|
+
organizationId: q.scope("organization"),
|
|
288
|
+
|
|
289
|
+
// Embedding column — stores JSON array of floats
|
|
290
|
+
embedding: q.text().optional(),
|
|
291
|
+
},
|
|
292
|
+
firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
|
|
293
|
+
crud: { list: {}, get: {}, create: {}, update: {}, delete: {} },
|
|
294
|
+
});
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
## Supported Models
|
|
298
|
+
|
|
299
|
+
Any Workers AI embedding model can be used:
|
|
300
|
+
|
|
301
|
+
| Model | Dimensions | Notes |
|
|
302
|
+
|-------|------------|-------|
|
|
303
|
+
| `@cf/baai/bge-base-en-v1.5` | 768 | Default, good general-purpose |
|
|
304
|
+
| `@cf/baai/bge-small-en-v1.5` | 384 | Faster, smaller |
|
|
305
|
+
| `@cf/baai/bge-large-en-v1.5` | 1024 | Higher quality |
|
|
306
|
+
|
|
307
|
+
See [Workers AI Models](https://developers.cloudflare.com/workers-ai/models/) for the full list.
|
|
308
|
+
|
|
309
|
+
## Deployment
|
|
310
|
+
|
|
311
|
+
After compiling with embeddings:
|
|
312
|
+
|
|
313
|
+
1. **Create the queue:**
|
|
314
|
+
```bash
|
|
315
|
+
wrangler queues create your-app-embeddings-queue
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
2. **Deploy the worker:**
|
|
319
|
+
```bash
|
|
320
|
+
wrangler deploy
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
The single worker handles both HTTP requests and queue consumption.
|
|
324
|
+
|
|
325
|
+
## Monitoring
|
|
326
|
+
|
|
327
|
+
Queue metrics are available in the Cloudflare dashboard:
|
|
328
|
+
- Messages enqueued
|
|
329
|
+
- Messages processed
|
|
330
|
+
- Retry count
|
|
331
|
+
- Consumer lag
|
|
332
|
+
|
|
333
|
+
Check queue health:
|
|
334
|
+
```bash
|
|
335
|
+
wrangler queues list
|
|
336
|
+
wrangler queues consumer your-app-embeddings-queue
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
## Error Handling
|
|
340
|
+
|
|
341
|
+
Failed jobs are automatically retried (up to `max_retries`):
|
|
342
|
+
|
|
343
|
+
```typescript
|
|
344
|
+
// In queue consumer
|
|
345
|
+
try {
|
|
346
|
+
const embedding = await env.AI.run(job.model, { text: job.content });
|
|
347
|
+
// ...
|
|
348
|
+
message.ack();
|
|
349
|
+
} catch (error) {
|
|
350
|
+
console.error('[Queue] Embedding job failed:', error);
|
|
351
|
+
message.retry(); // Will retry up to 3 times
|
|
352
|
+
}
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
After max retries, the message is dead-lettered (if configured) or dropped.
|
|
356
|
+
|
|
357
|
+
## Similarity Search Service
|
|
358
|
+
|
|
359
|
+
For applications that need typed similarity search with classification, you can define embedding search configurations using `defineEmbedding`. This generates a service layer with typed search functions.
|
|
360
|
+
|
|
361
|
+
### Defining Search Configurations
|
|
362
|
+
|
|
363
|
+
Create a file in `services/embeddings/`:
|
|
364
|
+
|
|
365
|
+
```typescript
|
|
366
|
+
// services/embeddings/job-similarity.ts
|
|
367
|
+
import { defineEmbedding } from '@quickback/compiler';
|
|
368
|
+
|
|
369
|
+
export default defineEmbedding({
|
|
370
|
+
name: 'job-similarity',
|
|
371
|
+
description: 'Find similar job postings by description content',
|
|
372
|
+
|
|
373
|
+
// Source configuration
|
|
374
|
+
source: 'jobs', // Table name
|
|
375
|
+
vectorIndex: 'VECTORIZE', // Binding name
|
|
376
|
+
model: '@cf/baai/bge-base-en-v1.5',
|
|
377
|
+
|
|
378
|
+
// Search configuration
|
|
379
|
+
search: {
|
|
380
|
+
threshold: 0.60, // Minimum similarity (default: 0.60)
|
|
381
|
+
limit: 10, // Max results (default: 10)
|
|
382
|
+
classify: {
|
|
383
|
+
DUPLICATE_POSTING: 0.90, // Score >= 0.90 = DUPLICATE_POSTING
|
|
384
|
+
SIMILAR_ROLE: 0.85, // Score >= 0.85 = SIMILAR_ROLE
|
|
385
|
+
RELATED: 0.75, // Score >= 0.75 = RELATED
|
|
386
|
+
},
|
|
387
|
+
filters: ['department', 'organizationId'], // Filterable fields
|
|
388
|
+
},
|
|
389
|
+
|
|
390
|
+
// Generation triggers (beyond CRUD)
|
|
391
|
+
triggers: {
|
|
392
|
+
onQueueMessage: 'embed_job', // Listen for queue messages
|
|
393
|
+
},
|
|
394
|
+
});
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
### Generated Service Layer
|
|
398
|
+
|
|
399
|
+
After compilation, a `createEmbeddings()` helper is generated in `src/lib/embeddings.ts`:
|
|
400
|
+
|
|
401
|
+
```typescript
|
|
402
|
+
import { createEmbeddings } from '../lib/embeddings';
|
|
403
|
+
|
|
404
|
+
export const execute: ActionExecutor = async ({ ctx, input }) => {
|
|
405
|
+
const embeddings = createEmbeddings(ctx.env);
|
|
406
|
+
|
|
407
|
+
// Search with automatic classification
|
|
408
|
+
const similar = await embeddings.jobSimilarity.search(
|
|
409
|
+
'Senior Full-Stack Engineer with React and Node.js experience',
|
|
410
|
+
{
|
|
411
|
+
department: 'engineering',
|
|
412
|
+
limit: 5,
|
|
413
|
+
threshold: 0.70,
|
|
414
|
+
}
|
|
415
|
+
);
|
|
416
|
+
|
|
417
|
+
// Returns: [{ id, score: 0.87, classification: 'SIMILAR_ROLE', metadata }]
|
|
418
|
+
for (const match of similar) {
|
|
419
|
+
console.log(`${match.classification}: ${match.id} (${match.score})`);
|
|
420
|
+
}
|
|
421
|
+
|
|
422
|
+
return { similar };
|
|
423
|
+
};
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
### Classification Thresholds
|
|
427
|
+
|
|
428
|
+
Results are automatically classified based on similarity score:
|
|
429
|
+
|
|
430
|
+
| Classification | Default Threshold | Meaning |
|
|
431
|
+
|----------------|-------------------|---------|
|
|
432
|
+
| `DUPLICATE_POSTING` | >= 0.90 | Near-identical job posting |
|
|
433
|
+
| `SIMILAR_ROLE` | >= 0.85 | Strongly similar role and requirements |
|
|
434
|
+
| `RELATED` | >= 0.75 | Topically related position |
|
|
435
|
+
| `NEW` | < 0.75 | No significant match |
|
|
436
|
+
|
|
437
|
+
Customize thresholds per use case:
|
|
438
|
+
|
|
439
|
+
```typescript
|
|
440
|
+
search: {
|
|
441
|
+
classify: {
|
|
442
|
+
DUPLICATE_POSTING: 0.95, // Stricter duplicate detection
|
|
443
|
+
SIMILAR_ROLE: 0.88,
|
|
444
|
+
RELATED: 0.70, // Broader "related" category
|
|
445
|
+
},
|
|
446
|
+
}
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
### Gray Zone Detection
|
|
450
|
+
|
|
451
|
+
For cases where automatic classification isn't sufficient, use gray zone detection to get matches that need semantic evaluation:
|
|
452
|
+
|
|
453
|
+
```typescript
|
|
454
|
+
const results = await embeddings.jobSimilarity.findWithGrayZone(
|
|
455
|
+
'Some job description text',
|
|
456
|
+
{ min: 0.60, max: 0.85 }
|
|
457
|
+
);
|
|
458
|
+
|
|
459
|
+
// Returns structured results:
|
|
460
|
+
// {
|
|
461
|
+
// high_confidence: [...], // Score >= 0.85 (auto-classified)
|
|
462
|
+
// gray_zone: [...] // 0.60 <= score < 0.85 (needs review)
|
|
463
|
+
// }
|
|
464
|
+
|
|
465
|
+
// Process high confidence matches automatically
|
|
466
|
+
for (const match of results.high_confidence) {
|
|
467
|
+
await markAsDuplicate(match.id);
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
// Queue gray zone for manual review
|
|
471
|
+
for (const match of results.gray_zone) {
|
|
472
|
+
await queueForReview(match.id, match.score);
|
|
473
|
+
}
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
### Generate Embeddings Directly
|
|
477
|
+
|
|
478
|
+
Generate embeddings without searching:
|
|
479
|
+
|
|
480
|
+
```typescript
|
|
481
|
+
const embeddings = createEmbeddings(ctx.env);
|
|
482
|
+
|
|
483
|
+
// Get raw embedding vector
|
|
484
|
+
const vector = await embeddings.jobSimilarity.embed(
|
|
485
|
+
'Text to embed'
|
|
486
|
+
);
|
|
487
|
+
// Returns: number[] (768 dimensions for bge-base)
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
### Multiple Search Configurations
|
|
491
|
+
|
|
492
|
+
Define different configurations for different use cases:
|
|
493
|
+
|
|
494
|
+
```typescript
|
|
495
|
+
// services/embeddings/candidate-similarity.ts
|
|
496
|
+
export default defineEmbedding({
|
|
497
|
+
name: 'candidate-similarity',
|
|
498
|
+
description: 'Match candidates by resume content',
|
|
499
|
+
source: 'candidates',
|
|
500
|
+
search: {
|
|
501
|
+
threshold: 0.65,
|
|
502
|
+
limit: 20,
|
|
503
|
+
classify: {
|
|
504
|
+
DUPLICATE_POSTING: 0.92,
|
|
505
|
+
SIMILAR_ROLE: 0.80,
|
|
506
|
+
RELATED: 0.65,
|
|
507
|
+
},
|
|
508
|
+
filters: ['source'],
|
|
509
|
+
},
|
|
510
|
+
});
|
|
511
|
+
|
|
512
|
+
// services/embeddings/application-match.ts
|
|
513
|
+
export default defineEmbedding({
|
|
514
|
+
name: 'application-match',
|
|
515
|
+
description: 'Match applications to similar job postings',
|
|
516
|
+
source: 'applications',
|
|
517
|
+
search: {
|
|
518
|
+
threshold: 0.70,
|
|
519
|
+
limit: 5,
|
|
520
|
+
classify: {
|
|
521
|
+
DUPLICATE_POSTING: 0.95,
|
|
522
|
+
SIMILAR_ROLE: 0.90,
|
|
523
|
+
RELATED: 0.80,
|
|
524
|
+
},
|
|
525
|
+
filters: ['jobId', 'organizationId'],
|
|
526
|
+
},
|
|
527
|
+
});
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
Usage:
|
|
531
|
+
```typescript
|
|
532
|
+
const embeddings = createEmbeddings(ctx.env);
|
|
533
|
+
|
|
534
|
+
// Different search behaviors for different content types
|
|
535
|
+
const similarJobs = await embeddings.jobSimilarity.search(text, opts);
|
|
536
|
+
const similarCandidates = await embeddings.candidateSimilarity.search(text, opts);
|
|
537
|
+
const matchingApplications = await embeddings.applicationMatch.search(text, opts);
|
|
538
|
+
```
|
|
539
|
+
|
|
540
|
+
### Table-Level vs Service-Level
|
|
541
|
+
|
|
542
|
+
| Feature | Table-level (`defineTable`) | Service-level (`defineEmbedding`) |
|
|
543
|
+
|---------|----------------------------|----------------------------------|
|
|
544
|
+
| Auto-embed on INSERT | ✅ | ❌ |
|
|
545
|
+
| Auto-embed on UPDATE | ✅ | ❌ |
|
|
546
|
+
| Custom search functions | ❌ | ✅ |
|
|
547
|
+
| Classification thresholds | ❌ | ✅ |
|
|
548
|
+
| Gray zone detection | ❌ | ✅ |
|
|
549
|
+
| Filterable searches | ❌ | ✅ |
|
|
550
|
+
| Queue message triggers | ❌ | ✅ |
|
|
551
|
+
|
|
552
|
+
**Use both together:**
|
|
553
|
+
- `defineTable` with `embeddings` config for automatic embedding generation
|
|
554
|
+
- `defineEmbedding` for typed search functions with classification
|