graphile-postgis 2.10.0 → 2.11.0

package/README.md

@@ -16,6 +16,31 @@ PostGIS support for PostGraphile v5.
 
 Automatically generates GraphQL types for PostGIS geometry and geography columns, including GeoJSON scalar types, dimension-aware interfaces, and subtype-specific fields (coordinates, points, rings, etc.).
 
+## The problem
+
+Working with PostGIS from an app is usually painful for one specific
+reason: **you end up juggling large amounts of GeoJSON across tables on
+the client**. You fetch every clinic as GeoJSON, fetch every county
+polygon as GeoJSON, and then — in the browser — loop through them
+yourself to figure out which clinic sits inside which county. Every
+query, every count, every page of results becomes a client-side
+geometry problem.
+
+An ORM generated automatically from your database schema can't fix this
+on its own. It sees a `geometry` column and stops there — it has no
+idea that "clinics inside a county" is the question you actually want
+to ask. Foreign keys tell it how tables relate by equality; nothing
+tells it how tables relate *spatially*.
+
+So we added the missing primitive: a **spatial relation**. You declare,
+on the database column, that `clinics.location` is "inside"
+`counties.geom`, and the generated GraphQL schema + ORM gain a
+first-class `where: { county: { some: { … } } }` shape that runs the
+join server-side, in one SQL query, using PostGIS and a GIST index. No
+GeoJSON on the wire, no client-side geometry, and the relation composes
+with the rest of your `where:` the same way a foreign-key relation
+would.
+
 ## Installation
 
 ```bash
@@ -40,8 +65,308 @@ const preset = {
 - Concrete types for all geometry subtypes: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection
 - Subtype-specific fields (x/y/z for Points, points for LineStrings, exterior/interiors for Polygons, etc.)
 - Geography-aware field naming (longitude/latitude/height instead of x/y/z)
+- Cross-table spatial relations via `@spatialRelation` smart tags (see below)
 - Graceful degradation when PostGIS is not installed
 
+## Spatial relations via smart tags
+
+You declare a **spatial relation** with a `@spatialRelation` smart tag
+on a `geometry` or `geography` column. The plugin turns that tag into a
+virtual relation on the owning table: a new field on the table's
+generated `where` input that runs a PostGIS join server-side. You write
+one line of SQL once; the generated ORM and GraphQL schema pick it up
+automatically.
+
+### At a glance
+
+**Before** — GeoJSON juggling on the client:
+
+```ts
+// 1. Pull every clinic's location as GeoJSON.
+const clinics = await gql(`{ telemedicineClinics { nodes { id name location } } }`);
+// 2. Pull the polygon of the one county you care about.
+const { geom } = await gql(`{ countyByName(name: "Bay County") { geom } }`);
+// 3. Run point-in-polygon on the client for each clinic.
+const inBay = clinics.telemedicineClinics.nodes.filter((c) =>
+  booleanPointInPolygon(c.location, geom),
+);
+```
+
+**After** — server-side, one trip:
+
+```sql
+COMMENT ON COLUMN telemedicine_clinics.location IS
+  E'@spatialRelation county counties.geom st_within';
+```
+
+```ts
+const inBay = await orm.telemedicineClinic
+  .findMany({
+    select: { id: true, name: true },
+    where: { county: { some: { name: { equalTo: 'Bay County' } } } },
+  })
+  .execute();
+```
+
+No polygon crosses the wire. The join happens in a single
+`EXISTS (…)` subquery on the server, using a PostGIS predicate on the
+two columns.
+
+### Declaring a relation
+
+#### Tag grammar
+
+```
+@spatialRelation <relationName> <targetRef> <operator> [<paramName>]
+```
+
+- `<relationName>` — user-chosen name for the new field on the owning
+  table's `where` input. Must match `/^[A-Za-z_][A-Za-z0-9_]*$/`. The
+  name is preserved as-written — `county` stays `county`,
+  `nearbyClinic` stays `nearbyClinic`.
+- `<targetRef>` — `table.column` (defaults to the owning column's
+  schema) or `schema.table.column` (for references in another schema,
+  e.g. a shared `geo` schema).
+- `<operator>` — one of the eight PG-native snake_case tokens listed in
+  [Operator reference](#operator-reference).
+- `<paramName>` — required if and only if the operator is parametric.
+  Today that's `st_dwithin`, which needs a parameter name (typically
+  `distance`).
+
+Both sides of the relation must be `geometry` or `geography`, and they
+must share the **same** base codec — you cannot mix `geometry` and
+`geography`.
+
+#### Multiple relations on one column
+
+Stack tags. Each line becomes its own field on the owning table's
+`where` input:
+
+```sql
+COMMENT ON COLUMN telemedicine_clinics.location IS
+  E'@spatialRelation county              counties.geom                  st_within\n'
+  '@spatialRelation intersectingCounty  counties.geom                  st_intersects\n'
+  '@spatialRelation coveringCounty      counties.geom                  st_coveredby\n'
+  '@spatialRelation nearbyClinic        telemedicine_clinics.location  st_dwithin distance';
+```
+
+The four relations above all exist in the integration test suite and
+can be used in the same query. Two relations on the same owner cannot
+share a `<relationName>`.
+
+### Operator reference
+
+| Tag operator | PostGIS function | Parametric? | Symmetric? | Typical use |
+|---|---|---|---|---|
+| `st_contains`        | `ST_Contains(A, B)`  | no          | **no** (A contains B) | polygon containing a point / line / polygon |
+| `st_within`          | `ST_Within(A, B)`    | no          | **no** (A within B)   | point-in-polygon, line-in-polygon |
+| `st_covers`          | `ST_Covers(A, B)`    | no          | **no**                | like `st_contains` but boundary-inclusive |
+| `st_coveredby`       | `ST_CoveredBy(A, B)` | no          | **no**                | dual of `st_covers` |
+| `st_intersects`      | `ST_Intersects(A, B)`| no          | yes                   | any overlap at all |
+| `st_equals`          | `ST_Equals(A, B)`    | no          | yes                   | exact geometry match |
+| `st_bbox_intersects` | `A && B` (infix)     | no          | yes                   | fast bounding-box prefilter |
+| `st_dwithin`         | `ST_DWithin(A, B, d)`| **yes** (`d`) | yes                 | radius / proximity search |
+
+> The tag reads left-to-right as **"owner op target"**, and the emitted
+> SQL is exactly `ST_<op>(owner_col, target_col[, distance])`. For
+> symmetric operators (`st_intersects`, `st_equals`, `st_dwithin`,
+> `st_bbox_intersects`) argument order doesn't matter. For directional
+> operators (`st_within`, `st_contains`, `st_covers`, `st_coveredby`),
+> flipping the two columns inverts the result set. Rule of thumb: put
+> the relation on the column whose type makes the sentence true —
+> `clinics.location st_within counties.geom` reads naturally; the
+> reverse does not.
+
+### Using the generated `where` shape
+
+#### Through the ORM
+
+```ts
+// "Clinics inside any county named 'Bay County'"
+await orm.telemedicineClinic
+  .findMany({
+    select: { id: true, name: true },
+    where: { county: { some: { name: { equalTo: 'Bay County' } } } },
+  })
+  .execute();
+```
+
+#### Through GraphQL
+
+The connection argument is `where:` at the GraphQL layer too — same
+name, same tree. Only the generated input **type** keeps the word
+"Filter" in it (e.g. `TelemedicineClinicFilter`):
+
+```graphql
+{
+  telemedicineClinics(
+    where: { county: { some: { name: { equalTo: "Bay County" } } } }
+  ) {
+    nodes { id name }
+  }
+}
+```
+
+#### `some` / `every` / `none`
+
+Every 2-argument relation exposes three modes. They mean what you'd
+expect, backed by `EXISTS` / `NOT EXISTS`:
+
+- `some: { <where clause> }` — the row matches if at least one related
+  target row passes the where clause.
+- `none: { <where clause> }` — the row matches if no related target row
+  passes.
+- `every: { <where clause> }` — the row matches when every related
+  target row passes (i.e. "no counter-example exists"). Note that
+  `every: {}` on an empty target set is vacuously true.
+
+An empty inner clause (`some: {}`) means "at least one related target
+row exists, any row will do" — so for `@spatialRelation county …
+st_within`, clinics whose point is inside zero counties are correctly
+excluded.
+
+#### Parametric operators (`st_dwithin` + `distance`)
+
+Parametric relations add a **required** `distance: Float!` field next
+to `some` / `every` / `none`. The distance parametrises the join
+itself, not the inner `some:` clause:
+
+```ts
+await orm.telemedicineClinic
+  .findMany({
+    select: { id: true, name: true },
+    where: {
+      nearbyClinic: {
+        distance: 5000,
+        some: { specialty: { equalTo: 'pediatrics' } },
+      },
+    },
+  })
+  .execute();
+```
+
+Distance units follow PostGIS semantics:
+
+| Owner codec | `distance` units |
+|---|---|
+| `geography` | meters |
+| `geometry`  | SRID coordinate units (degrees for SRID 4326) |
+
+#### Composition with `and` / `or` / `not` and scalar where clauses
+
+Spatial relations live in the same `where:` tree as every scalar
+predicate and compose the same way:
+
+```ts
+// AND — Bay County clinics that are cardiology
+where: {
+  and: [
+    { county: { some: { name: { equalTo: 'Bay County' } } } },
+    { specialty: { equalTo: 'cardiology' } },
+  ],
+}
+
+// OR — Bay County clinics OR the one named "LA Pediatrics"
+where: {
+  or: [
+    { county: { some: { name: { equalTo: 'Bay County' } } } },
+    { name: { equalTo: 'LA Pediatrics' } },
+  ],
+}
+
+// NOT — clinics that are NOT in Bay County
+where: {
+  not: { county: { some: { name: { equalTo: 'Bay County' } } } },
+}
+```
+
+Inside `some` / `every` / `none`, the inner where clause is the target
+table's full `where` input — every scalar predicate the target exposes
+is available.
+
+### Self-relations
+
+When the owner and target columns are the same column, the plugin
+emits a self-exclusion predicate so a row never matches itself:
+
+- Single-column primary key: `other.<pk> <> self.<pk>`
+- Composite primary key: `(other.a, other.b) IS DISTINCT FROM (self.a, self.b)`
+
+Tables without a primary key are rejected at schema build — a
+self-relation there would match every row against itself.
+
+One concrete consequence: with `st_dwithin`, a self-relation at
+`distance: 0` matches zero rows, because the only candidate at
+distance 0 is the row itself, which is excluded.
+
+### Generated SQL shape
+
+```sql
+SELECT ...
+FROM <owner_table> self
+WHERE EXISTS (
+  SELECT 1
+  FROM <target_table> other
+  WHERE ST_<op>(self.<owner_col>, other.<target_col>[, <distance>])
+    AND <self-exclusion for self-relations>
+    AND <nested some/every/none conditions>
+);
+```
+
+The EXISTS lives inside the owner's generated `where` input, so it
+composes with pagination, ordering, and the rest of the outer plan.
+`st_bbox_intersects` compiles to infix `&&` rather than a function call.
+PostGIS functions are called with whichever schema PostGIS is installed
+in, so non-`public` installs work without configuration.
+
+### Indexing
+
+Spatial predicates without a GIST index fall back to sequential scans,
+which is almost never what you want. The plugin checks your target
+columns at schema-build time and emits a non-fatal warning when a GIST
+index is missing, including the recommended `CREATE INDEX ... USING
+GIST(...)` in the warning text.
+
+```sql
+CREATE INDEX ON telemedicine_clinics USING GIST(location);
+CREATE INDEX ON counties              USING GIST(geom);
+```
+
+If a particular column is a known exception (e.g. a small prototype
+table), set `@spatialRelationSkipIndexCheck` on that column to suppress
+the warning.
+
+### `geometry` vs `geography`
+
+Pick one side of a relation and stick with it — mixing codecs across
+the two sides is rejected at schema build. `geography` distances are
+always meters; `geometry` distances follow the SRID's native units
+(degrees for SRID 4326, which is rarely what you want for radius
+searches). If you need meter-based proximity on a `geometry` column,
+cast on ingest (`::geography`) rather than mixing codecs across a
+single relation.
+
+### FAQ
+
+- **"Why doesn't `some: {}` return every row?"** — because `some` means
+  "at least one related target row exists". Rows whose column has no
+  match on the other side are correctly excluded.
+- **"Why does `distance: 0` on a self-relation return nothing?"** — the
+  self-exclusion predicate removes the row's match with itself, so at
+  distance 0 no candidates remain.
+- **"Can I reuse a `relationName` across tables?"** — yes; uniqueness
+  is scoped to the owning table.
+- **"Can I declare the relation from the polygon side instead of the
+  point side?"** — yes. Flip owner and target and use the inverse
+  operator (`st_contains` in place of `st_within`). Same rows, same
+  SQL, different `where` location.
+- **"Does this work with PostGIS installed in a non-`public` schema?"**
+  — yes.
+- **"Can I use a spatial relation in `orderBy` or on a connection
+  field?"** — no; it's a where-only construct. Use PostGIS measurement
+  fields (see the `geometry-fields` / `measurement-fields` plugins) for
+  values you want to sort on.
+
 ## License
 
 MIT

package/esm/index.d.ts

@@ -21,6 +21,8 @@ export { PostgisGeometryFieldsPlugin } from './plugins/geometry-fields';
 export { PostgisMeasurementFieldsPlugin } from './plugins/measurement-fields';
 export { PostgisTransformationFieldsPlugin } from './plugins/transformation-functions';
 export { PostgisAggregatePlugin } from './plugins/aggregate-functions';
+export { PostgisSpatialRelationsPlugin, OPERATOR_REGISTRY, parseSpatialRelationTag, collectSpatialRelations, } from './plugins/spatial-relations';
+export type { SpatialOperatorRegistration, SpatialRelationInfo, } from './plugins/spatial-relations';
 export { createPostgisOperatorFactory } from './plugins/connection-filter-operators';
 export { createWithinDistanceOperatorFactory } from './plugins/within-distance-operator';
 export { GisSubtype, SUBTYPE_STRING_BY_SUBTYPE, GIS_SUBTYPE_NAME, CONCRETE_SUBTYPES } from './constants';

package/esm/index.js

@@ -23,6 +23,7 @@ export { PostgisGeometryFieldsPlugin } from './plugins/geometry-fields';
 export { PostgisMeasurementFieldsPlugin } from './plugins/measurement-fields';
 export { PostgisTransformationFieldsPlugin } from './plugins/transformation-functions';
 export { PostgisAggregatePlugin } from './plugins/aggregate-functions';
+export { PostgisSpatialRelationsPlugin, OPERATOR_REGISTRY, parseSpatialRelationTag, collectSpatialRelations, } from './plugins/spatial-relations';
 // Connection filter operator factories (spatial operators for graphile-connection-filter)
 export { createPostgisOperatorFactory } from './plugins/connection-filter-operators';
 export { createWithinDistanceOperatorFactory } from './plugins/within-distance-operator';

package/esm/plugins/connection-filter-operators.js

@@ -207,6 +207,8 @@ export function createPostgisOperatorFactory() {
         }
         const { inflection } = build;
         const { schemaName, geometryCodec, geographyCodec } = postgisInfo;
+        const sqlGeomFromGeoJSON = sql.identifier(schemaName, 'st_geomfromgeojson');
+        const sqlGeographyType = sql.identifier(schemaName, 'geography');
         // Collect all GQL type names for geometry and geography
         const gqlTypeNamesByBase = {
             geometry: [],
@@ -239,6 +241,7 @@ export function createPostgisOperatorFactory() {
                     typeNames: gqlTypeNamesByBase[baseType],
                     operatorName,
                     description,
+                    baseType: baseType,
                     resolve: (i, v) => sql.fragment `${sqlGisFunction}(${i}, ${v})`
                 });
             }
@@ -252,6 +255,7 @@ export function createPostgisOperatorFactory() {
                     typeNames: gqlTypeNamesByBase[baseType],
                     operatorName,
                     description,
+                    baseType: baseType,
                     resolve: (i, v) => buildOperatorExpr(capturedOp, i, v)
                 });
             }
@@ -261,8 +265,21 @@ export function createPostgisOperatorFactory() {
         // Convert to ConnectionFilterOperatorRegistration format.
         // Each InternalSpec may target multiple type names; we expand each
         // into individual registrations keyed by typeName.
+        //
+        // The default operatorApply pipeline binds the filter value as a raw
+        // text parameter cast to the column codec's sqlType (geometry /
+        // geography). PostgreSQL's geometry_in / geography_in parsers reject
+        // GeoJSON text, so we must wrap the input with ST_GeomFromGeoJSON
+        // ourselves — see within-distance-operator.ts for the pattern.
+        //
+        // We disable the default bind via `resolveSqlValue: () => sql.null`
+        // and construct the geometry value from `input` inside resolve(),
+        // mirroring the ST_DWithin implementation.
         const registrations = [];
         for (const spec of allSpecs) {
+            const geographyCast = spec.baseType === 'geography'
+                ? sql.fragment `::${sqlGeographyType}`
+                : sql.fragment ``;
             for (const typeName of spec.typeNames) {
                 registrations.push({
                     typeNames: typeName,
@@ -270,8 +287,11 @@ export function createPostgisOperatorFactory() {
                     spec: {
                         description: spec.description,
                         resolveType: (fieldType) => fieldType,
-                        resolve(sqlIdentifier, sqlValue, _input, _$where, _details) {
-                            return spec.resolve(sqlIdentifier, sqlValue);
+                        resolveSqlValue: () => sql.null,
+                        resolve(sqlIdentifier, _sqlValue, input, _$where, _details) {
+                            const geoJsonStr = sql.value(JSON.stringify(input));
+                            const geomSql = sql.fragment `${sqlGeomFromGeoJSON}(${geoJsonStr}::text)${geographyCast}`;
+                            return spec.resolve(sqlIdentifier, geomSql);
                         }
                     },
                 });

package/esm/plugins/spatial-relations.d.ts

@@ -0,0 +1,130 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import 'graphile-connection-filter';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * PostgisSpatialRelationsPlugin
+ *
+ * Adds cross-table spatial filtering to `graphile-connection-filter` by
+ * reading a `@spatialRelation` smart tag on geometry/geography columns and
+ * synthesising a virtual relation + filter field that emits an EXISTS
+ * subquery joined by a PostGIS predicate (e.g. `ST_Contains`, `ST_DWithin`).
+ *
+ * The regular `ConnectionFilterBackwardRelationsPlugin` is FK-driven — it
+ * joins on column equality. Spatial relationships are not backed by FKs, so
+ * this plugin hooks the same `pgCodec`-scoped filter input types and injects
+ * its own fields whose `apply()` emits `ST_<op>(...)` instead of `a = b`.
+ *
+ * Tag grammar:
+ *
+ * ```sql
+ * COMMENT ON COLUMN <owner_table>.<owner_col> IS
+ *   E'@spatialRelation <relation_name> <target_ref> <operator> [<param_name>]';
+ * ```
+ *
+ * - `target_ref` — `schema.table.col` or `table.col` (same schema as owner).
+ * - `operator` — one of the PG-native snake_case ops in OPERATOR_REGISTRY.
+ * - `param_name` — required iff the operator is parametric (currently
+ *   only `st_dwithin`, which needs a distance).
+ *
+ * Examples:
+ *
+ * ```sql
+ * -- Point in polygon
+ * COMMENT ON COLUMN telemedicine_clinics.location IS
+ *   E'@spatialRelation county counties.geom st_contains';
+ *
+ * -- Self-referential radius search
+ * COMMENT ON COLUMN telemedicine_clinics.location IS
+ *   E'@spatialRelation nearbyClinic telemedicine_clinics.location st_dwithin distance';
+ * ```
+ *
+ * Generated GraphQL (for the `st_dwithin` case):
+ *
+ * ```graphql
+ * telemedicineClinics(where: {
+ *   nearbyClinic: {
+ *     distance: 5000,
+ *     some: { specialty: { eq: "pediatrics" } }
+ *   }
+ * })
+ * ```
+ *
+ * The generated SQL uses the same EXISTS pattern as backward relations but
+ * substitutes `ST_<op>(...)` for column equality:
+ *
+ * ```sql
+ * WHERE EXISTS (
+ *   SELECT 1 FROM <target_table> other
+ *   WHERE ST_<op>(other.<target_col>, self.<owner_col>[, distance])
+ *     AND other.<pk> <> self.<pk>  -- self-relations only
+ *     AND <nested filter conditions>
+ * )
+ * ```
+ */
+export interface SpatialOperatorRegistration {
+    /** Tag-facing op name (PG-native snake_case). */
+    name: string;
+    /** Kind of PG-level operator. */
+    kind: 'function' | 'infix';
+    /**
+     * For `kind: 'function'`, the PG function name (snake_case) resolved
+     * against the PostGIS schema at SQL-emit time. For `kind: 'infix'`,
+     * the PG binary operator token (e.g. `&&`).
+     */
+    pgToken: string;
+    /** Whether this op takes an extra numeric parameter (e.g. `st_dwithin`). */
+    parametric: boolean;
+    description: string;
+}
+export declare const OPERATOR_REGISTRY: Record<string, SpatialOperatorRegistration>;
+export interface SpatialRelationInfo {
+    /** GraphQL-facing relation name, derived from the tag. */
+    relationName: string;
+    /** The codec that owns the tag (outer side of the EXISTS). */
+    ownerCodec: any;
+    /** The owning attribute name (column). */
+    ownerAttributeName: string;
+    /** Qualified target resource (inner side of the EXISTS). */
+    targetResource: any;
+    /** Column name on the target resource. */
+    targetAttributeName: string;
+    /** Resolved operator. */
+    operator: SpatialOperatorRegistration;
+    /** Field name for the parametric argument, if any. */
+    paramFieldName: string | null;
+    /** Whether owner === target (self-relation needs row exclusion). */
+    isSelfRelation: boolean;
+    /**
+     * Cached primary-key attribute names for the owner+target codecs. Used
+     * to synthesise the self-exclusion predicate (`other.<pk> <> self.<pk>`).
+     * `null` if the codec has no discoverable PK.
+     */
+    ownerPkAttributes: string[] | null;
+    targetPkAttributes: string[] | null;
+}
+interface TagParseResult {
+    ok: true;
+    relationName: string;
+    targetRef: string;
+    operator: string;
+    paramName: string | null;
+}
+interface TagParseError {
+    ok: false;
+    error: string;
+}
+/**
+ * Parse a single `@spatialRelation` tag value.
+ *
+ * Accepts a string of the form `<name> <target> <op> [<param>]`.
+ */
+export declare function parseSpatialRelationTag(raw: string): TagParseResult | TagParseError;
+/**
+ * Build the full set of spatial relations from all resources.
+ * Validates tags and throws (at schema build) on anything malformed.
+ * Returns relations keyed by (owner codec identity, relation name).
+ */
+export declare function collectSpatialRelations(build: any): SpatialRelationInfo[];
+export declare const PostgisSpatialRelationsPlugin: GraphileConfig.Plugin;
+export {};