graphile-search 2.19.9 → 2.19.10

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