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/README.md CHANGED
@@ -53,11 +53,21 @@ const preset = {
53
53
  - **4 search algorithms** via adapters: tsvector (ts_rank), BM25 (pg_textsearch), pg_trgm (similarity), pgvector (distance)
54
54
  - **Per-algorithm score fields**: `{column}{Algorithm}{Metric}` (e.g. `bodyBm25Score`, `titleTrgmSimilarity`)
55
55
  - **Composite `searchScore`**: Normalized 0..1 aggregating all active search signals
56
- - **OrderBy enums**: `{COLUMN}_{ALGORITHM}_{METRIC}_ASC/DESC` + `SEARCH_SCORE_ASC/DESC`
56
+ - **OrderBy enums**: `{COLUMN}_{ALGORITHM}_{METRIC}_ASC/DESC` + `SEARCH_SCORE_ASC/DESC` (see [Ordering by a score](#ordering-by-a-score))
57
57
  - **Filter fields**: `{algorithm}{Column}` on connection filter input types
58
58
  - **Hybrid search**: Combine multiple algorithms in a single query
59
59
  - **Zero config**: Auto-discovers columns and indexes per adapter
60
60
 
61
+ ## Ordering by a score
62
+
63
+ A search orderBy sorts by the score its filter computes, so it needs that filter in `where`: `BODY_BM25_SCORE_ASC` needs `bm25Body` (or `unifiedSearch`), `SEARCH_SCORE_DESC` needs any search filter. A search orderBy without its filter is an error that names the filter to add.
64
+
65
+ `SEARCH_SCORE_ASC/DESC` orders by the same Reciprocal Rank Fusion sum that `searchScore` displays. The ranks are computed once, in a subquery over the table's matching rows that is joined to the query on the primary key, so the order is a plain column and `first`/`after` and `last`/`before` cursors work; tied scores (equal evidence shares a rank) are separated by the primary key.
66
+
67
+ When a column is scored by both its own filter (e.g. `bm25Body`) and `unifiedSearch`, the explicit filter's score is the one displayed and ordered by; the column is scored once per query.
68
+
69
+ Limitation: in a *literal* `orderBy` list, plain column terms are planned before search-score terms, so `[EMBEDDING_VECTOR_DISTANCE_ASC, ROW_ID_ASC]` sorts by `ROW_ID` first. Pass `orderBy` as a GraphQL variable to keep the requested order, or do not mix search terms with column terms in a literal list.
70
+
61
71
  ## Architecture
62
72
 
63
73
  ```
package/adapters/bm25.js CHANGED
@@ -87,7 +87,8 @@ function createBm25Adapter(options = {}) {
87
87
  // registrations, so we catch and ignore.
88
88
  try {
89
89
  build.registerInputObjectType('Bm25SearchInput', {}, () => ({
90
- description: 'Input for BM25 ranked text search. Provide a search query string and optional score threshold.',
90
+ description: 'Input for BM25 ranked text search. Provide a search query string and an optional maximum score. ' +
91
+ 'Only rows the query matches (negative score) are returned.',
91
92
  fields: () => ({
92
93
  query: {
93
94
  type: new GraphQLNonNull(GraphQLString),
@@ -95,7 +96,8 @@ function createBm25Adapter(options = {}) {
95
96
  },
96
97
  threshold: {
97
98
  type: GraphQLFloat,
98
- description: 'Maximum BM25 score threshold (negative values). Only rows with score <= threshold are returned.',
99
+ description: 'Maximum BM25 score (scores are negative; more negative = better match). ' +
100
+ 'Only rows with score <= threshold are returned.',
99
101
  },
100
102
  }),
101
103
  }), 'UnifiedSearchPlugin (bm25 adapter) registering Bm25SearchInput type');
@@ -120,6 +122,12 @@ function createBm25Adapter(options = {}) {
120
122
  const qualifiedIndexName = `"${bm25Index.schemaName}"."${bm25Index.indexName}"`;
121
123
  const bm25queryExpr = sql `to_bm25query(${sql.value(query)}, ${sql.value(qualifiedIndexName)})`;
122
124
  const scoreExpr = sql `(${columnExpr} <@> ${bm25queryExpr})`;
125
+ // A bm25 score is negative for a match and 0 for a row the query does
126
+ // not match, so the filter keeps negative scores. Without this the
127
+ // result would depend on whether the planner used the bm25 index.
128
+ const matchClause = (score) => threshold !== undefined && threshold !== null
129
+ ? sql `(${score} < 0 AND ${score} <= ${sql.value(threshold)})`
130
+ : sql `${score} < 0`;
123
131
  // Check for chunk-aware querying
124
132
  const chunksInfo = columnData.chunksInfo;
125
133
  if (chunksInfo && chunksInfo.searchIndexes.includes('bm25') && (includeChunks !== false)) {
@@ -147,22 +155,14 @@ function createBm25Adapter(options = {}) {
147
155
  COALESCE(${scoreExpr}, 0::real),
148
156
  COALESCE(${chunkScoreSubquery}, 0::real)
149
157
  )`;
150
- let whereClause = null;
151
- if (threshold !== undefined && threshold !== null) {
152
- whereClause = sql `${combinedScoreExpr} < ${sql.value(threshold)}`;
153
- }
154
158
  return {
155
- whereClause,
159
+ whereClause: matchClause(combinedScoreExpr),
156
160
  scoreExpression: combinedScoreExpr,
157
161
  };
158
162
  }
159
163
  // Standard (non-chunk) query
160
- let whereClause = null;
161
- if (threshold !== undefined && threshold !== null) {
162
- whereClause = sql `${scoreExpr} < ${sql.value(threshold)}`;
163
- }
164
164
  return {
165
- whereClause,
165
+ whereClause: matchClause(scoreExpr),
166
166
  scoreExpression: scoreExpr,
167
167
  };
168
168
  },
@@ -84,7 +84,8 @@ export function createBm25Adapter(options = {}) {
84
84
  // registrations, so we catch and ignore.
85
85
  try {
86
86
  build.registerInputObjectType('Bm25SearchInput', {}, () => ({
87
- description: 'Input for BM25 ranked text search. Provide a search query string and optional score threshold.',
87
+ description: 'Input for BM25 ranked text search. Provide a search query string and an optional maximum score. ' +
88
+ 'Only rows the query matches (negative score) are returned.',
88
89
  fields: () => ({
89
90
  query: {
90
91
  type: new GraphQLNonNull(GraphQLString),
@@ -92,7 +93,8 @@ export function createBm25Adapter(options = {}) {
92
93
  },
93
94
  threshold: {
94
95
  type: GraphQLFloat,
95
- description: 'Maximum BM25 score threshold (negative values). Only rows with score <= threshold are returned.',
96
+ description: 'Maximum BM25 score (scores are negative; more negative = better match). ' +
97
+ 'Only rows with score <= threshold are returned.',
96
98
  },
97
99
  }),
98
100
  }), 'UnifiedSearchPlugin (bm25 adapter) registering Bm25SearchInput type');
@@ -117,6 +119,12 @@ export function createBm25Adapter(options = {}) {
117
119
  const qualifiedIndexName = `"${bm25Index.schemaName}"."${bm25Index.indexName}"`;
118
120
  const bm25queryExpr = sql `to_bm25query(${sql.value(query)}, ${sql.value(qualifiedIndexName)})`;
119
121
  const scoreExpr = sql `(${columnExpr} <@> ${bm25queryExpr})`;
122
+ // A bm25 score is negative for a match and 0 for a row the query does
123
+ // not match, so the filter keeps negative scores. Without this the
124
+ // result would depend on whether the planner used the bm25 index.
125
+ const matchClause = (score) => threshold !== undefined && threshold !== null
126
+ ? sql `(${score} < 0 AND ${score} <= ${sql.value(threshold)})`
127
+ : sql `${score} < 0`;
120
128
  // Check for chunk-aware querying
121
129
  const chunksInfo = columnData.chunksInfo;
122
130
  if (chunksInfo && chunksInfo.searchIndexes.includes('bm25') && (includeChunks !== false)) {
@@ -144,22 +152,14 @@ export function createBm25Adapter(options = {}) {
144
152
  COALESCE(${scoreExpr}, 0::real),
145
153
  COALESCE(${chunkScoreSubquery}, 0::real)
146
154
  )`;
147
- let whereClause = null;
148
- if (threshold !== undefined && threshold !== null) {
149
- whereClause = sql `${combinedScoreExpr} < ${sql.value(threshold)}`;
150
- }
151
155
  return {
152
- whereClause,
156
+ whereClause: matchClause(combinedScoreExpr),
153
157
  scoreExpression: combinedScoreExpr,
154
158
  };
155
159
  }
156
160
  // Standard (non-chunk) query
157
- let whereClause = null;
158
- if (threshold !== undefined && threshold !== null) {
159
- whereClause = sql `${scoreExpr} < ${sql.value(threshold)}`;
160
- }
161
161
  return {
162
- whereClause,
162
+ whereClause: matchClause(scoreExpr),
163
163
  scoreExpression: scoreExpr,
164
164
  };
165
165
  },