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/README.md +11 -1
- package/adapters/bm25.js +12 -12
- package/esm/adapters/bm25.js +12 -12
- package/esm/plugin.js +357 -79
- package/package.json +5 -5
- package/plugin.js +357 -79
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
|
|
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
|
|
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
|
},
|
package/esm/adapters/bm25.js
CHANGED
|
@@ -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
|
|
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
|
|
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
|
},
|