graphile-search 2.19.9 → 2.19.11

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/esm/plugin.js CHANGED
@@ -45,6 +45,27 @@ function getSearchConfig(codec) {
45
45
  return raw;
46
46
  return undefined;
47
47
  }
48
+ /**
49
+ * Resolve the composite searchScore settings for a table: per-table
50
+ * @searchConfig first, then the plugin's global options.
51
+ */
52
+ function resolveSearchScoreConfig(codec, globalWeights) {
53
+ const tableSearchConfig = getSearchConfig(codec);
54
+ let boostRecent = tableSearchConfig?.boost_recent ?? false;
55
+ const boostRecencyField = tableSearchConfig?.boost_recency_field ?? 'updated_at';
56
+ let missingRecencyField = null;
57
+ if (boostRecent && boostRecencyField && !codec.attributes[boostRecencyField]) {
58
+ missingRecencyField = boostRecencyField;
59
+ boostRecent = false;
60
+ }
61
+ return {
62
+ weights: tableSearchConfig?.weights ?? globalWeights,
63
+ boostRecent,
64
+ boostRecencyField,
65
+ boostRecencyDecay: tableSearchConfig?.boost_recency_decay ?? 0.95,
66
+ missingRecencyField,
67
+ };
68
+ }
48
69
  /**
49
70
  * Map a raw score to 0..1 for effective rank estimation in the RRF fallback path.
50
71
  * Used only when a rank window function is not available for an adapter.
@@ -94,15 +115,135 @@ function applyRecencyBoost(normalizedScore, recencyValue, decay) {
94
115
  */
95
116
  export function createUnifiedSearchPlugin(options) {
96
117
  const { adapters, enableSearchScore = true, enableUnifiedSearch = true, rrfK = 60 } = options;
97
- // Per-codec cache of discovered columns, keyed by codec name
98
- const codecCache = new Map();
99
- // Bridge between orderBy enum apply and filter apply.
100
- // The orderBy enum runs on the PgSelectStep while the filter runs on
101
- // a separate query-builder object. They share the same SQL `alias`
102
- // reference, so we use a WeakMap keyed by that alias to pass the
103
- // requested sort direction from the orderBy (which fires first) to
104
- // the filter (which fires second and has the score expression).
105
- const _pendingOrderDirections = new WeakMap();
118
+ // Discovered columns per codec. One plugin instance can build several
119
+ // schemas (a shared preset), and two builds can have codecs with the same
120
+ // name but different attributes, so the cache is keyed by build and then
121
+ // by codec identity, never by name.
122
+ const codecCache = new WeakMap();
123
+ const SEARCH_SCORE_ORDER_KEY = 'unified_order_search_score';
124
+ // Set when the query reads searchScore or orders by SEARCH_SCORE_*: only
125
+ // then are ranks computed (they need a second scan of the table).
126
+ const RANKS_WANTED_KEY = 'unified_search_ranks_wanted';
127
+ // A search orderBy needs the direction (from the orderBy enum) and the
128
+ // score expression (from the filter). The filter always applies at
129
+ // runtime; a literal orderBy applies at plan time, before it, and a
130
+ // variable orderBy applies at runtime, after it. Each side stores its
131
+ // half in the query builder's meta, which is copied per execution, and
132
+ // whichever side runs second adds the ORDER BY.
133
+ //
134
+ // The ORDER BY spec object is kept in meta so a later filter can swap
135
+ // the expression in place (pgSelect renders `orders` after every apply
136
+ // has run): unifiedSearch adds adapters to the composite score one at a
137
+ // time, and an explicit column filter replaces the unifiedSearch score
138
+ // for the same column.
139
+ function setSearchOrder(qb, orderKey, fragment, nulls) {
140
+ const direction = qb.getMetaRaw(`${orderKey}__direction`);
141
+ if (!direction)
142
+ return;
143
+ const spec = qb.getMetaRaw(`${orderKey}__spec`);
144
+ if (spec) {
145
+ spec.fragment = fragment;
146
+ return;
147
+ }
148
+ const newSpec = { fragment, codec: TYPES.float, direction };
149
+ if (nulls)
150
+ newSpec.nulls = nulls;
151
+ qb.orderBy(newSpec);
152
+ qb.setMeta(`${orderKey}__spec`, newSpec);
153
+ }
154
+ function orderBySearchScore(qb, orderKey) {
155
+ const fragment = qb.getMetaRaw(`${orderKey}__score`);
156
+ if (fragment)
157
+ setSearchOrder(qb, orderKey, fragment);
158
+ }
159
+ // SEARCH_SCORE_* orders by the same Reciprocal Rank Fusion sum the
160
+ // searchScore field displays: each active adapter contributes
161
+ // weight / (k + rank), rank being the row's position by that adapter's
162
+ // score. The field divides by a per-query constant to land in 0..1,
163
+ // which does not change the order, so the SQL skips it.
164
+ //
165
+ // Ranks are window functions, which cannot appear in the WHERE a cursor
166
+ // becomes, so they are computed in a subquery over the table's matching
167
+ // rows that is LEFT JOINed to the query on the primary key. The outer
168
+ // query then orders by, pages on and displays plain columns of that join.
169
+ function getScoringState(qb, sql) {
170
+ let state = qb.getMetaRaw(`${SEARCH_SCORE_ORDER_KEY}__scoring`);
171
+ if (!state) {
172
+ state = {
173
+ alias: sql.identifier(Symbol('search_scores')),
174
+ innerAlias: sql.identifier(Symbol('search_scores_rows')),
175
+ slots: new Map(),
176
+ nextSlot: 0,
177
+ joinSpec: null,
178
+ };
179
+ qb.setMeta(`${SEARCH_SCORE_ORDER_KEY}__scoring`, state);
180
+ }
181
+ return state;
182
+ }
183
+ function rankColumn(slot, sql) {
184
+ return sql.identifier(`rank_${slot.n}`);
185
+ }
186
+ function scoreColumn(slot, sql) {
187
+ return sql.identifier(`score_${slot.n}`);
188
+ }
189
+ function buildScoringSubquery(state, source, scoreConfig, sql) {
190
+ const t = state.innerAlias;
191
+ const r = sql.identifier(Symbol('search_scores_ranked'));
192
+ const slots = [...state.slots.values()];
193
+ const keyColumns = source.uniqueAttributes.map((name) => sql.identifier(name));
194
+ const recency = scoreConfig.boostRecent ? sql.identifier('recency') : null;
195
+ const innerSelects = keyColumns.map((c) => sql `${t}.${c}`);
196
+ if (recency) {
197
+ innerSelects.push(sql `${t}.${sql.identifier(scoreConfig.boostRecencyField)} AS ${recency}`);
198
+ }
199
+ const terms = [];
200
+ for (const slot of slots) {
201
+ const rank = rankColumn(slot, sql);
202
+ const direction = slot.lowerIsBetter ? sql.fragment `ASC` : sql.fragment `DESC`;
203
+ // Scores such as similarity() and ts_rank() are real; the cursor
204
+ // round-trips them through the float8 codec, so the ORDER BY must
205
+ // compare as float8 too or the boundary row repeats on `before`.
206
+ innerSelects.push(sql `${slot.score}::float8 AS ${scoreColumn(slot, sql)}`);
207
+ // RANK(): rows with the same score share a rank, so equal evidence
208
+ // gives an equal composite score (the primary key then orders them).
209
+ // A row without a score has no rank: otherwise it would be handed the
210
+ // position right after the scored ones.
211
+ innerSelects.push(sql `(CASE WHEN ${slot.score} IS NULL THEN NULL ELSE RANK() OVER (ORDER BY ${slot.score} ${direction} NULLS LAST) END) AS ${rank}`);
212
+ terms.push(sql `CASE WHEN ${r}.${rank} IS NULL THEN 0::float8 ELSE ${sql.literal(slot.weight)}::float8 / (${sql.literal(rrfK)}::float8 + ${r}.${rank}) END`);
213
+ }
214
+ let score = sql `(${sql.join(terms, ' + ')})`;
215
+ if (recency) {
216
+ const age = sql `GREATEST(0::float8, EXTRACT(EPOCH FROM (now() - ${r}.${recency}))::float8 / 86400)`;
217
+ score = sql `${score} * CASE WHEN ${r}.${recency} IS NULL THEN 1::float8 ELSE power(${sql.literal(scoreConfig.boostRecencyDecay)}::float8, ${age}) END`;
218
+ }
219
+ const inner = sql `SELECT ${sql.join(innerSelects, ', ')} FROM ${source.from} AS ${t} WHERE ${sql.join(slots.map((slot) => sql.parens(slot.matches)), ' OR ')}`;
220
+ const outerSelects = [
221
+ ...keyColumns.map((c) => sql `${r}.${c}`),
222
+ ...slots.map((slot) => sql `${r}.${scoreColumn(slot, sql)}`),
223
+ ...slots.map((slot) => sql `${r}.${rankColumn(slot, sql)}`),
224
+ sql `${score}::float8 AS ${sql.identifier('score')}`,
225
+ ];
226
+ return sql `(SELECT ${sql.join(outerSelects, ', ')} FROM (${inner}) AS ${r})`;
227
+ }
228
+ function orderByCompositeScore(qb, sql) {
229
+ const state = qb.getMetaRaw(`${SEARCH_SCORE_ORDER_KEY}__scoring`);
230
+ if (!state || state.slots.size === 0)
231
+ return;
232
+ setSearchOrder(qb, SEARCH_SCORE_ORDER_KEY, sql `${state.alias}.${sql.identifier('score')}`, 'LAST');
233
+ }
234
+ /**
235
+ * The table the composite score ranks rows in, joined back on its
236
+ * primary key. Null when the codec has no table or no unique key.
237
+ */
238
+ function getScoringSource(codec, build) {
239
+ const resource = build.pgTableResource?.(codec);
240
+ if (!resource || typeof resource.from === 'function')
241
+ return null;
242
+ const unique = resource.uniques?.[0];
243
+ if (!unique || unique.attributes.length === 0)
244
+ return null;
245
+ return { from: resource.from, uniqueAttributes: unique.attributes };
246
+ }
106
247
  /**
107
248
  * Get (or compute) the adapter columns for a given codec.
108
249
  *
@@ -116,10 +257,14 @@ export function createUnifiedSearchPlugin(options) {
116
257
  * count as intentional search.
117
258
  */
118
259
  function getAdapterColumns(codec, build) {
119
- const cacheKey = codec.name;
120
- if (codecCache.has(cacheKey)) {
121
- return codecCache.get(cacheKey);
260
+ let buildCache = codecCache.get(build);
261
+ if (!buildCache) {
262
+ buildCache = new WeakMap();
263
+ codecCache.set(build, buildCache);
122
264
  }
265
+ const cached = buildCache.get(codec);
266
+ if (cached)
267
+ return cached;
123
268
  const primaryAdapters = adapters.filter((a) => !a.isSupplementary);
124
269
  const supplementaryAdapters = adapters.filter((a) => a.isSupplementary);
125
270
  // Phase 1: Run non-supplementary adapters (tsvector, BM25, pgvector, etc.)
@@ -152,9 +297,40 @@ export function createUnifiedSearchPlugin(options) {
152
297
  }
153
298
  }
154
299
  }
155
- codecCache.set(cacheKey, results);
300
+ buildCache.set(codec, results);
156
301
  return results;
157
302
  }
303
+ /**
304
+ * The filter fields that give an adapter's column a score: the column's
305
+ * own filter, and unifiedSearch when the adapter takes part in it.
306
+ */
307
+ function filtersScoring(adapter, column, inflection) {
308
+ const names = [inflection.camelCase(`${adapter.filterPrefix}_${column.attributeName}`)];
309
+ if (enableUnifiedSearch && (adapter.supportsTextSearch || adapter.name === 'vector')) {
310
+ names.push('unifiedSearch');
311
+ }
312
+ return names;
313
+ }
314
+ /** Filter field names present (non-null) anywhere in a `where` value. */
315
+ function collectFilterFields(where, into) {
316
+ if (Array.isArray(where)) {
317
+ for (const item of where)
318
+ collectFilterFields(item, into);
319
+ }
320
+ else if (where && typeof where === 'object') {
321
+ for (const [key, value] of Object.entries(where)) {
322
+ if (value == null)
323
+ continue;
324
+ if (key === 'and' || key === 'or' || key === 'not') {
325
+ collectFilterFields(value, into);
326
+ }
327
+ else {
328
+ into.add(key);
329
+ }
330
+ }
331
+ }
332
+ return into;
333
+ }
158
334
  return {
159
335
  name: 'UnifiedSearchPlugin',
160
336
  version: '1.0.0',
@@ -265,6 +441,91 @@ export function createUnifiedSearchPlugin(options) {
265
441
  }
266
442
  return _;
267
443
  },
444
+ /**
445
+ * A search orderBy only has a score to order by when the filter that
446
+ * computes it is active. Validate `orderBy` against `where` on every
447
+ * collection field of a searchable table and fail the request with
448
+ * the filter that is missing, instead of silently returning rows in
449
+ * primary key order.
450
+ */
451
+ GraphQLObjectType_fields_field(field, build, context) {
452
+ const { inflection, grafast: { lambda, constant }, } = build;
453
+ const { scope: { isPgFieldConnection, isPgFieldSimpleCollection, pgFieldResource }, } = context;
454
+ if (!isPgFieldConnection && !isPgFieldSimpleCollection)
455
+ return field;
456
+ const codec = pgFieldResource?.codec;
457
+ if (!codec?.attributes || codec.isAnonymous)
458
+ return field;
459
+ const adapterColumns = getAdapterColumns(codec, build);
460
+ if (adapterColumns.length === 0)
461
+ return field;
462
+ const plan = field.plan;
463
+ if (typeof plan !== 'function')
464
+ return field;
465
+ const requiredFilters = new Map();
466
+ const anySearchFilter = new Set();
467
+ for (const { adapter, columns } of adapterColumns) {
468
+ for (const column of columns) {
469
+ const filters = filtersScoring(adapter, column, inflection);
470
+ filters.forEach((f) => anySearchFilter.add(f));
471
+ for (const ascending of [true, false]) {
472
+ const name = inflection.pgSearchOrderByEnum(codec, column.attributeName, adapter.name, adapter.scoreSemantics.metric, ascending);
473
+ requiredFilters.set(name, filters);
474
+ }
475
+ }
476
+ }
477
+ if (enableSearchScore) {
478
+ const all = [...anySearchFilter];
479
+ requiredFilters.set(inflection.constantCase('search_score_asc'), all);
480
+ requiredFilters.set(inflection.constantCase('search_score_desc'), all);
481
+ }
482
+ const compositeOrders = enableSearchScore
483
+ ? [inflection.constantCase('search_score_asc'), inflection.constantCase('search_score_desc')]
484
+ : [];
485
+ const hasScoringSource = getScoringSource(codec, build) != null;
486
+ function validateOrderBy(orderBy, where) {
487
+ if (orderBy == null)
488
+ return;
489
+ const values = Array.isArray(orderBy) ? orderBy : [orderBy];
490
+ let present = null;
491
+ for (const value of values) {
492
+ const name = String(value);
493
+ const filters = requiredFilters.get(name);
494
+ if (!filters)
495
+ continue;
496
+ present ??= collectFilterFields(where, new Set());
497
+ if (!filters.some((f) => present.has(f))) {
498
+ throw new Error(`Cannot order by ${name} without a search filter that scores it: ` +
499
+ `add ${filters.map((f) => `where.${f}`).join(' or ')}.`);
500
+ }
501
+ if (!hasScoringSource && compositeOrders.includes(name)) {
502
+ throw new Error(`Cannot order by ${name}: the composite score is joined on the table's ` +
503
+ 'primary key, and this table has none.');
504
+ }
505
+ }
506
+ }
507
+ return {
508
+ ...field,
509
+ plan($parent, fieldArgs, info) {
510
+ const $result = plan($parent, fieldArgs, info);
511
+ const argNames = (info?.field?.args ?? []).map((a) => a.name);
512
+ if ($result == null || !argNames.includes('orderBy'))
513
+ return $result;
514
+ const $select = typeof $result.getSubplan === 'function' ? $result.getSubplan() : $result;
515
+ if (typeof $select?.apply !== 'function')
516
+ return $result;
517
+ const $where = argNames.includes('where') ? fieldArgs.getRaw('where') : constant(null);
518
+ $select.apply(lambda([fieldArgs.getRaw('orderBy'), $where], ([orderBy, where]) => {
519
+ validateOrderBy(orderBy, where);
520
+ const values = Array.isArray(orderBy) ? orderBy : [orderBy];
521
+ if (!values.some((v) => compositeOrders.includes(String(v))))
522
+ return undefined;
523
+ return (qb) => qb.setMeta(RANKS_WANTED_KEY, true);
524
+ }));
525
+ return $result;
526
+ },
527
+ };
528
+ },
268
529
  /**
269
530
  * Add score/rank/similarity/distance fields for each adapter's columns
270
531
  * on the appropriate output types.
@@ -341,21 +602,12 @@ export function createUnifiedSearchPlugin(options) {
341
602
  });
342
603
  }
343
604
  }
344
- // Read per-table @searchConfig smart tag (written by SearchUnified/SearchFullText/SearchBm25)
345
- // Per-table config overrides global searchScoreWeights
346
- const tableSearchConfig = getSearchConfig(codec);
347
- // Resolve effective weights: per-table > global > equal (undefined)
348
- const effectiveWeights = tableSearchConfig?.weights ?? options.searchScoreWeights;
349
- // Recency boost config from per-table smart tag
350
- let boostRecent = tableSearchConfig?.boost_recent ?? false;
351
- const boostRecencyField = tableSearchConfig?.boost_recency_field ?? 'updated_at';
352
- const boostRecencyDecay = tableSearchConfig?.boost_recency_decay ?? 0.95;
353
- // Phase I: Validate that the recency field actually exists on the table.
354
- // If it doesn't, disable recency boost gracefully instead of crashing at query time.
355
- if (boostRecent && boostRecencyField && !codec.attributes[boostRecencyField]) {
356
- console.warn(`[graphile-search] @searchConfig.boost_recency_field "${boostRecencyField}" ` +
605
+ const scoreConfig = resolveSearchScoreConfig(codec, options.searchScoreWeights);
606
+ const effectiveWeights = scoreConfig.weights;
607
+ const { boostRecent, boostRecencyField, boostRecencyDecay } = scoreConfig;
608
+ if (scoreConfig.missingRecencyField) {
609
+ console.warn(`[graphile-search] @searchConfig.boost_recency_field "${scoreConfig.missingRecencyField}" ` +
357
610
  `not found on table "${codec.name}". Recency boost disabled for this table.`);
358
- boostRecent = false;
359
611
  }
360
612
  newFields = build.extend(newFields, {
361
613
  searchScore: fieldWithHooks({
@@ -377,6 +629,7 @@ export function createUnifiedSearchPlugin(options) {
377
629
  if (typeof $select.setInliningForbidden === 'function') {
378
630
  $select.setInliningForbidden();
379
631
  }
632
+ $select.setMeta(RANKS_WANTED_KEY, true);
380
633
  // Collect all meta steps for all adapters
381
634
  const $metaSteps = allMetaKeys.map((mk) => $select.getMeta(mk.metaKey));
382
635
  // If recency boost is configured, inject the recency field into
@@ -388,10 +641,9 @@ export function createUnifiedSearchPlugin(options) {
388
641
  }
389
642
  // Capture the index in a local const for the lambda closure
390
643
  const capturedRecencyIndex = recencySelectIndex;
391
- // For RRF we also need rank expressions. Inject ROW_NUMBER()
392
- // window functions for each adapter score into the SELECT.
393
- // These will be populated at filter-apply time via meta.
394
- // We store a meta key suffix "__rank" alongside the score.
644
+ // RRF needs each adapter's rank for the row. The filter
645
+ // apply selects it from the scoring join and records the
646
+ // select index under the "__rank" meta key.
395
647
  const rankMetaKeys = allMetaKeys.map((mk) => `${mk.metaKey}__rank`);
396
648
  const $rankMetaSteps = rankMetaKeys.map((key) => $select.getMeta(key));
397
649
  return lambda([...$metaSteps, ...$rankMetaSteps, $row], (args) => {
@@ -489,18 +741,9 @@ export function createUnifiedSearchPlugin(options) {
489
741
  attributeName: column.attributeName,
490
742
  });
491
743
  const orderKey = `unified_order_${adapter.name}_${baseFieldName}`;
492
- const makePlan = (direction) => (step) => {
493
- // Store the requested direction keyed by the SQL alias so
494
- // the filter's apply (which runs second) can read it.
495
- const aliasKey = step?.alias;
496
- if (aliasKey) {
497
- let dirs = _pendingOrderDirections.get(aliasKey);
498
- if (!dirs) {
499
- dirs = {};
500
- _pendingOrderDirections.set(aliasKey, dirs);
501
- }
502
- dirs[orderKey] = direction;
503
- }
744
+ const makePlan = (direction) => (qb) => {
745
+ qb.setMeta(`${orderKey}__direction`, direction);
746
+ orderBySearchScore(qb, orderKey);
504
747
  };
505
748
  const ascName = inflection.pgSearchOrderByEnum(codec, column.attributeName, adapter.name, adapter.scoreSemantics.metric, true);
506
749
  const descName = inflection.pgSearchOrderByEnum(codec, column.attributeName, adapter.name, adapter.scoreSemantics.metric, false);
@@ -526,16 +769,9 @@ export function createUnifiedSearchPlugin(options) {
526
769
  if (enableSearchScore && adapterColumns.length > 0) {
527
770
  const searchScoreAscName = inflection.constantCase('search_score_asc');
528
771
  const searchScoreDescName = inflection.constantCase('search_score_desc');
529
- const makeSearchScorePlan = (direction) => (step) => {
530
- const aliasKey = step?.alias;
531
- if (aliasKey) {
532
- let dirs = _pendingOrderDirections.get(aliasKey);
533
- if (!dirs) {
534
- dirs = {};
535
- _pendingOrderDirections.set(aliasKey, dirs);
536
- }
537
- dirs['unified_order_search_score'] = direction;
538
- }
772
+ const makeSearchScorePlan = (direction) => (qb) => {
773
+ qb.setMeta(`${SEARCH_SCORE_ORDER_KEY}__direction`, direction);
774
+ orderByCompositeScore(qb, build.sql);
539
775
  };
540
776
  newValues = build.extend(newValues, {
541
777
  [searchScoreAscName]: {
@@ -565,39 +801,76 @@ export function createUnifiedSearchPlugin(options) {
565
801
  const { scope: { isPgConnectionFilter, pgCodec } = {}, fieldWithHooks, } = context;
566
802
  /**
567
803
  * Inject a single adapter's score expression + rank window function
568
- * into the query builder, and apply any pending ORDER BY direction.
804
+ * into the query builder, and add its ORDER BY if one was requested.
569
805
  *
570
806
  * Shared by per-adapter filter fields AND the unifiedSearch
571
807
  * composite filter (both text and vector adapter branches).
808
+ *
809
+ * A column is scored once per query: its own filter field wins
810
+ * over unifiedSearch, whichever applied first.
572
811
  */
573
- function injectScoreAndRank(qb, adapter, column, result, codec_, $condition) {
812
+ function injectScoreAndRank(qb, adapter, column, applyFor, codec_, source, scoreConfig, scoring) {
574
813
  if (!qb || qb.mode !== 'normal')
575
814
  return;
815
+ const result = applyFor(qb.alias);
816
+ if (!result)
817
+ return;
576
818
  const baseFieldName = inflection.attribute({
577
819
  codec: codec_,
578
820
  attributeName: column.attributeName,
579
821
  });
580
822
  const scoreMetaKey = `__unified_search_${adapter.name}_${baseFieldName}`;
581
- const wrappedScoreSql = sql `${sql.parens(result.scoreExpression)}::text`;
582
- const scoreIndex = qb.selectAndReturnIndex(wrappedScoreSql);
583
- qb.setMeta(scoreMetaKey, { selectIndex: scoreIndex });
584
- const rankMetaKey = `${scoreMetaKey}__rank`;
585
- const orderDirection = adapter.scoreSemantics.lowerIsBetter ? 'ASC' : 'DESC';
586
- // A row without a score has no rank: otherwise ROW_NUMBER() would
587
- // hand unscored rows the positions right after the scored ones.
588
- const rankSql = sql `(CASE WHEN ${sql.parens(result.scoreExpression)} IS NULL THEN NULL ELSE ROW_NUMBER() OVER (ORDER BY ${sql.parens(result.scoreExpression)} ${orderDirection === 'ASC' ? sql.fragment `ASC` : sql.fragment `DESC`} NULLS LAST) END)::text`;
589
- const rankIndex = qb.selectAndReturnIndex(rankSql);
590
- qb.setMeta(rankMetaKey, { selectIndex: rankIndex });
823
+ const existing = qb.getMetaRaw(scoreMetaKey);
824
+ if (existing && (existing.source === 'explicit' || source === 'unified'))
825
+ return;
826
+ const score = sql.parens(result.scoreExpression);
827
+ const scoreIndex = qb.selectAndReturnIndex(sql `${score}::text`);
828
+ qb.setMeta(scoreMetaKey, { selectIndex: scoreIndex, source });
591
829
  const orderKey = `unified_order_${adapter.name}_${baseFieldName}`;
592
- const dirs = _pendingOrderDirections.get($condition.alias);
593
- const explicitDir = dirs?.[orderKey];
594
- if (explicitDir) {
595
- qb.orderBy({
596
- fragment: result.scoreExpression,
597
- codec: TYPES.float,
598
- direction: explicitDir,
599
- });
830
+ const wantsRanks = qb.getMetaRaw(RANKS_WANTED_KEY) || qb.getMetaRaw(`${SEARCH_SCORE_ORDER_KEY}__direction`);
831
+ if (!scoring || !wantsRanks) {
832
+ // Scores such as similarity() and ts_rank() are real; the cursor
833
+ // round-trips them through the float8 codec, so the ORDER BY must
834
+ // compare as float8 too or the boundary row repeats on `before`.
835
+ qb.setMeta(`${orderKey}__score`, sql `${score}::float8`);
836
+ orderBySearchScore(qb, orderKey);
837
+ return;
838
+ }
839
+ const state = getScoringState(qb, sql);
840
+ const inner = applyFor(state.innerAlias);
841
+ if (!inner)
842
+ return;
843
+ const previous = state.slots.get(scoreMetaKey);
844
+ const slot = {
845
+ n: previous?.n ?? state.nextSlot++,
846
+ weight: scoreConfig.weights?.[adapter.name] ?? 1,
847
+ lowerIsBetter: adapter.scoreSemantics.lowerIsBetter,
848
+ score: sql.parens(inner.scoreExpression),
849
+ matches: inner.whereClause ?? inner.scorableClause ?? sql.true,
850
+ };
851
+ state.slots.set(scoreMetaKey, slot);
852
+ const rankIndex = qb.selectAndReturnIndex(sql `${state.alias}.${rankColumn(slot, sql)}::text`);
853
+ qb.setMeta(`${scoreMetaKey}__rank`, { selectIndex: rankIndex });
854
+ // With the scoring join in the query, every search ORDER BY reads a
855
+ // column of it: a bm25 `<@>` in an outer ORDER BY is rewritten by
856
+ // its extension to read the score of "the current" index scan, and
857
+ // with the join there are two.
858
+ qb.setMeta(`${orderKey}__score`, sql `${state.alias}.${scoreColumn(slot, sql)}`);
859
+ orderBySearchScore(qb, orderKey);
860
+ const from = buildScoringSubquery(state, scoring, scoreConfig, sql);
861
+ if (state.joinSpec) {
862
+ state.joinSpec.from = from;
863
+ }
864
+ else {
865
+ state.joinSpec = {
866
+ type: 'left',
867
+ from,
868
+ alias: state.alias,
869
+ conditions: scoring.uniqueAttributes.map((name) => sql `${state.alias}.${sql.identifier(name)} = ${qb.alias}.${sql.identifier(name)}`),
870
+ };
871
+ qb.join(state.joinSpec);
600
872
  }
873
+ orderByCompositeScore(qb, sql);
601
874
  }
602
875
  if (!isPgConnectionFilter ||
603
876
  !pgCodec ||
@@ -610,6 +883,8 @@ export function createUnifiedSearchPlugin(options) {
610
883
  if (adapterColumns.length === 0) {
611
884
  return fields;
612
885
  }
886
+ const scoreConfig = resolveSearchScoreConfig(codec, options.searchScoreWeights);
887
+ const scoring = enableSearchScore ? getScoringSource(codec, build) : null;
613
888
  let newFields = fields;
614
889
  // ── StringFilter → StringTrgmFilter type swapping ──
615
890
  // For tables that qualify for trgm, swap the type of string attribute
@@ -649,7 +924,8 @@ export function createUnifiedSearchPlugin(options) {
649
924
  apply: function plan($condition, val) {
650
925
  if (val == null)
651
926
  return;
652
- const result = adapter.buildFilterApply(sql, $condition.alias, column, val, build);
927
+ const applyFor = (alias) => adapter.buildFilterApply(sql, alias, column, val, build);
928
+ const result = applyFor($condition.alias);
653
929
  if (!result)
654
930
  return;
655
931
  // Apply WHERE clause
@@ -661,7 +937,7 @@ export function createUnifiedSearchPlugin(options) {
661
937
  $condition.where(result.scorableClause);
662
938
  }
663
939
  const qb = getQueryBuilder(build, $condition);
664
- injectScoreAndRank(qb, adapter, column, result, codec, $condition);
940
+ injectScoreAndRank(qb, adapter, column, applyFor, codec, 'explicit', scoreConfig, scoring);
665
941
  },
666
942
  }),
667
943
  }, `UnifiedSearchPlugin adding ${adapter.name} filter field '${fieldName}' for '${column.attributeName}' on '${codec.name}'`);
@@ -714,26 +990,28 @@ export function createUnifiedSearchPlugin(options) {
714
990
  for (const column of columns) {
715
991
  // Convert text to adapter-specific filter input
716
992
  const filterInput = adapter.buildTextSearchInput(text);
717
- const result = adapter.buildFilterApply(sql, $condition.alias, column, filterInput, build);
993
+ const applyFor = (alias) => adapter.buildFilterApply(sql, alias, column, filterInput, build);
994
+ const result = applyFor($condition.alias);
718
995
  if (!result)
719
996
  continue;
720
997
  if (result.whereClause) {
721
998
  whereClauses.push(result.whereClause);
722
999
  }
723
- injectScoreAndRank(qb, adapter, column, result, codec, $condition);
1000
+ injectScoreAndRank(qb, adapter, column, applyFor, codec, 'unified', scoreConfig, scoring);
724
1001
  }
725
1002
  }
726
1003
  // Vector adapters (pgvector) — only when __vector is injected
727
1004
  if (vector && vectorAdapterColumns.length > 0) {
728
1005
  for (const { adapter, columns } of vectorAdapterColumns) {
729
1006
  for (const column of columns) {
730
- const result = adapter.buildFilterApply(sql, $condition.alias, column, { vector, metric: 'COSINE' }, build);
1007
+ const applyFor = (alias) => adapter.buildFilterApply(sql, alias, column, { vector, metric: 'COSINE' }, build);
1008
+ const result = applyFor($condition.alias);
731
1009
  if (!result)
732
1010
  continue;
733
1011
  if (result.whereClause) {
734
1012
  whereClauses.push(result.whereClause);
735
1013
  }
736
- injectScoreAndRank(qb, adapter, column, result, codec, $condition);
1014
+ injectScoreAndRank(qb, adapter, column, applyFor, codec, 'unified', scoreConfig, scoring);
737
1015
  }
738
1016
  }
739
1017
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "graphile-search",
3
- "version": "2.19.9",
3
+ "version": "2.19.11",
4
4
  "description": "Unified PostGraphile v5 search plugin — abstracts tsvector, BM25, pg_trgm, and pgvector behind a single adapter-based architecture with composite searchScore",
5
5
  "author": "Constructive <developers@constructive.io>",
6
6
  "homepage": "https://github.com/constructive-io/constructive",
@@ -34,11 +34,11 @@
34
34
  "devDependencies": {
35
35
  "@types/node": "^22.19.11",
36
36
  "@types/pg": "^8.20.4",
37
- "graphile-connection-filter": "^2.19.9",
38
- "graphile-test": "^5.19.9",
37
+ "graphile-connection-filter": "^2.19.10",
38
+ "graphile-test": "^5.19.10",
39
39
  "makage": "^0.8.0",
40
40
  "pg": "^8.21.0",
41
- "pgsql-test": "^5.20.8"
41
+ "pgsql-test": "^5.20.9"
42
42
  },
43
43
  "peerDependencies": {
44
44
  "@dataplan/pg": "^1.1.1",
@@ -65,5 +65,5 @@
65
65
  "hybrid-search",
66
66
  "searchScore"
67
67
  ],
68
- "gitHead": "eb44afc5ecdfa6e91aeb7ad8e24c9021b97ec027"
68
+ "gitHead": "93d6ff9000e85f53b5f75dae12eeb0f9e4ce566f"
69
69
  }