Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 81 additions & 0 deletions .agents/skills/graphile-file-urls/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
---
name: graphile-file-urls
description: Read URLs for a file-reference column (an `image` or `upload` jsonb domain column, scalar or array) from GraphQL — `<col>Url(width)` and `<col>Versions` returning `FileVersion`, added by graphile-presigned-url-plugin. Use when asked to "show an image at a size", "get a thumbnail URL", "get the URL of an uploaded file on a row", "srcset", "why is photoUrl null", or when adding a new file-reference domain (`fileRefDomains`).
compatibility: PostGraphile v5, graphile-presigned-url-plugin, graphile-storage-registry
metadata:
author: constructive-io
version: "1.0.0"
---

# File-reference column URLs

Source: `graphile/graphile-presigned-url-plugin/src/file-ref-urls.ts`
(`createFileRefUrlsPlugin`, installed by `PresignedUrlPreset`).

## What you get

For every column whose type is a jsonb domain named in `FILE_REF_DOMAINS`
(`['image', 'upload']`, `graphile/graphile-storage-registry/src/naming.ts`), or
an array of one, the row type gains two fields:

```graphql
type Product {
photo: JSON
photoUrl(width: Int): String # image or upload column
photoVersions: [FileVersion!]
gallery: [JSON]
galleryUrl(width: Int): [String] # array column: one entry per element
galleryVersions: [[FileVersion!]]
}

type FileVersion {
name: String
key: String!
width: Int
height: Int
format: String
size: Int
url: String!
}
```

- `<col>Url` without `width`: the source file's URL.
- `<col>Url(width: N)`: the narrowest rendered version at least `N` wide; when
no version is that wide (or the document has none, as on an `upload`
column), the source URL.
- `<col>Versions`: the versions in the document, narrowest first, each with a
URL. Empty when there are none. Use it for `srcset`.
- `null` when the file id is unknown, hidden from the reader by RLS, not live,
or its bucket is not reconciled.

```graphql
{ products { nodes { photoUrl(width: 480) photoVersions { width url } resumeUrl } } }
```

Use these on business tables. `downloadUrl` is the field on a files-table row;
it is still there and behaves the same for bucket handling (public bucket with
`publicUrlPrefix` → direct URL, private → presigned GET).

## Rules the resolver keeps

- The file row is read by the document's `id` under the reader's RLS. The
document's own `key`, bucket and filename are ignored.
- A version is signed only if its key is a direct child of that row's
`<source-key>.versions/` (`isVersionKeyOf`). Anything else in the document's
`versions` is dropped.
- `.versions/` is reserved: a client-supplied upload key containing it is
refused with `INVALID_KEY` (`src/custom-key.ts`).
- Lookups are batched per request: one files query per storage module for all
rows of a list, not one per row.

## Adding a file type

Pass the full list as the plugin option `fileRefDomains` (`src/types.ts`), or
add the name to `FILE_REF_DOMAINS`. The domain must be a jsonb domain whose
document carries the files row `id`. Do not add a per-type plugin.

## Where versions come from

The database writes them: constructive-db's `ProcessImageVersions` lane stores
`versions` inside the image document. This plugin only reads the document; a
column with no versions still resolves `<col>Url` to the source.
1 change: 1 addition & 0 deletions .agents/skills/graphile-search/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -267,6 +267,7 @@ This avoids the problem of BM25/pgvector producing unbounded scores that can't b
| `includeChunks` field missing | No `@hasChunks` tables in schema | Add `@hasChunks` smart tag to parent table codec |
| `Unknown type "FullText"` | TsvectorCodecPlugin not loaded | Use `UnifiedSearchPreset()` which includes all codecs |
| `Unknown type "Vector"` | VectorCodecPlugin not loaded | Use `UnifiedSearchPreset()` which includes all codecs |
| Vector search returns nothing after changing the embedding model | Rows are stamped with the old model in the `@embeddingModelOf` column | Re-embed the rows; see `references/pgvector-adapter.md` |
| Duplicate type errors | Multiple search presets | Use only `UnifiedSearchPreset()`, not individual presets |

## Related Skills
Expand Down
30 changes: 30 additions & 0 deletions .agents/skills/graphile-search/references/pgvector-adapter.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,36 @@ query {
}
```

## Model-Aware Search (`@embeddingModel` / `@embeddingModelOf`)

Vectors of two models are not comparable. The adapter reads two smart tags
(`graphile/graphile-search/src/adapters/pgvector.ts`, `detectColumns`):

| Tag | On | Meaning |
|-----|----|---------|
| `@embeddingModel <model>` | the vector column | the model the column's definition names |
| `@embeddingModelOf <vector column>` | a sibling text column | records, per row, the model that produced that row's vector |

constructive-db's `SearchVector` generator emits both (`<field>_model` carries
`@embeddingModelOf`; `@embeddingModel` only when the node names a model).

- The vector filter input has a `model` field. On a column with a model
column, when `model` is given only rows whose stamp equals it are compared;
rows stamped with another model (or not stamped) are skipped until they are
embedded again with that model.
- With `graphile-llm`, a search `text` is embedded once per model its columns
use (`@embeddingModel`, else the request's model) and `model` is filled in
server-side (`graphile/graphile-llm/src/embed-inputs.ts`). A column whose
embedding failed sits the search out; it is never searched with another
model's vector.
- On write, `graphile-llm`'s `<column>Text` mutation input embeds with the
column's `@embeddingModel` and, when the `@embeddingModelOf` column is in
the mutation input, writes the model used into it
(`graphile/graphile-llm/src/plugins/text-mutation-plugin.ts`).
- Passing a raw `vector` yourself: pass `model` too, or rows of every model
are compared.
- A column with neither tag behaves as before.

## VectorCodecPlugin

The `VectorCodecPlugin` (included in `UnifiedSearchPreset`) teaches PostGraphile about the `vector` PostgreSQL type:
Expand Down
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,7 @@ The `.agents/skills/` directory contains tooling-focused skills for this monorep
| `constructive-testing` | PostgreSQL testing frameworks — pgsql-test, drizzle-orm-test, supabase-test | Writing database tests, testing RLS policies, seeding test data |
| `constructive-cli` | Generated CLI commands — how the CLI is generated from GraphQL schemas, codegen options, multi-target CLI | Generating CLI tools, running generated CLI, understanding codegen pipeline |
| `graphile-search` | Unified PostGraphile v5 search plugin — tsvector, BM25, pg_trgm, pgvector adapters, composite searchScore | Adding search to GraphQL, configuring search adapters, querying search via SDK |
| `graphile-file-urls` | `<col>Url(width)` / `<col>Versions` / `FileVersion` on `image` and `upload` columns (graphile-presigned-url-plugin) | Reading a sized image URL or an uploaded file's URL from a business-table row, adding a file-reference domain |

## Tips

Expand Down