@undefineds.co/xpod 0.3.6 → 0.3.14

package/dist/storage/rdf/Rdf3xTripleIndex.js

@@ -0,0 +1,1235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Rdf3xTripleIndex = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const n3_1 = require("n3");
+const SqliteRuntime_1 = require("../SqliteRuntime");
+const RdfTermDictionary_1 = require("./RdfTermDictionary");
+const RdfTermSemantics_1 = require("./RdfTermSemantics");
+const TERM_COLUMN = {
+    subject: 'subject_id',
+    predicate: 'predicate_id',
+    object: 'object_id',
+};
+const ORDER_COLUMN = {
+    graph: 'graph_id',
+    ...TERM_COLUMN,
+};
+const PATTERN_COLUMNS = {
+    graph: 'graph_id',
+    ...TERM_COLUMN,
+};
+const TERM_KEYS = ['subject', 'predicate', 'object'];
+const PERMUTATIONS = [
+    { name: 'SPO', table: 'rdf3x_spo', columns: ['subject_id', 'predicate_id', 'object_id'] },
+    { name: 'SOP', table: 'rdf3x_sop', columns: ['subject_id', 'object_id', 'predicate_id'] },
+    { name: 'PSO', table: 'rdf3x_pso', columns: ['predicate_id', 'subject_id', 'object_id'] },
+    { name: 'POS', table: 'rdf3x_pos', columns: ['predicate_id', 'object_id', 'subject_id'] },
+    { name: 'OSP', table: 'rdf3x_osp', columns: ['object_id', 'subject_id', 'predicate_id'] },
+    { name: 'OPS', table: 'rdf3x_ops', columns: ['object_id', 'predicate_id', 'subject_id'] },
+];
+const PAIR_PROJECTIONS = [
+    { name: 'SP', table: 'rdf3x_stat_sp', columns: ['subject_id', 'predicate_id'], remainder: 'object_id' },
+    { name: 'SO', table: 'rdf3x_stat_so', columns: ['subject_id', 'object_id'], remainder: 'predicate_id' },
+    { name: 'PS', table: 'rdf3x_stat_ps', columns: ['predicate_id', 'subject_id'], remainder: 'object_id' },
+    { name: 'PO', table: 'rdf3x_stat_po', columns: ['predicate_id', 'object_id'], remainder: 'subject_id' },
+    { name: 'OS', table: 'rdf3x_stat_os', columns: ['object_id', 'subject_id'], remainder: 'predicate_id' },
+    { name: 'OP', table: 'rdf3x_stat_op', columns: ['object_id', 'predicate_id'], remainder: 'subject_id' },
+];
+const TERM_PROJECTIONS = [
+    { name: 'S', table: 'rdf3x_stat_s', column: 'subject_id' },
+    { name: 'P', table: 'rdf3x_stat_p', column: 'predicate_id' },
+    { name: 'O', table: 'rdf3x_stat_o', column: 'object_id' },
+];
+class Rdf3xTripleIndex {
+    constructor(options) {
+        this.options = options;
+        this.sqliteRuntime = (0, SqliteRuntime_1.createSqliteRuntime)();
+        this.db = null;
+        this.dictionary = null;
+    }
+    open() {
+        if (this.db) {
+            return;
+        }
+        if (this.options.path !== ':memory:') {
+            const dir = (0, node_path_1.dirname)(this.options.path);
+            if (!(0, node_fs_1.existsSync)(dir)) {
+                (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+            }
+        }
+        this.db = this.sqliteRuntime.openDatabase(this.options.path);
+        this.dictionary = new RdfTermDictionary_1.RdfTermDictionary(this.db);
+        this.dictionary.initialize();
+        this.initializeSchema();
+    }
+    close() {
+        this.db?.close();
+        this.db = null;
+        this.dictionary = null;
+    }
+    clear() {
+        this.clearRdf3xTables();
+    }
+    rebuildFromCurrentQuads() {
+        const start = Date.now();
+        const db = this.requireDb();
+        const scannedQuads = db.prepare('SELECT COUNT(*) AS count FROM rdf_quads').get()?.count ?? 0;
+        db.transaction(() => {
+            this.clearRdf3xTables();
+            db.prepare(`
+        INSERT INTO rdf3x_triple_membership (
+          graph_id,
+          subject_id,
+          predicate_id,
+          object_id,
+          source_file_id,
+          source_line_no
+        )
+        SELECT
+          graph_id,
+          subject_id,
+          predicate_id,
+          object_id,
+          source_file_id,
+          source_line_no
+        FROM rdf_quads
+      `).run();
+            for (const permutation of PERMUTATIONS) {
+                db.prepare(`
+          INSERT OR IGNORE INTO ${permutation.table} (${permutation.columns.join(', ')})
+          SELECT DISTINCT ${permutation.columns.join(', ')}
+          FROM rdf_quads
+        `).run();
+            }
+            for (const projection of PAIR_PROJECTIONS) {
+                this.rebuildPairProjection(projection);
+            }
+            for (const projection of TERM_PROJECTIONS) {
+                this.rebuildTermProjection(projection);
+            }
+        })();
+        const stats = this.stats();
+        return {
+            scannedQuads,
+            uniqueTriples: stats.uniqueTriples,
+            memberships: stats.membershipCount,
+            projectionRows: pairProjectionRowTotal(stats.pairProjectionRows) + termProjectionRowTotal(stats.termProjectionRows),
+            durationMs: Date.now() - start,
+        };
+    }
+    scan(pattern, options) {
+        const start = Date.now();
+        const resolved = this.resolvePattern(pattern);
+        if (resolved.unresolved) {
+            return {
+                quads: [],
+                metrics: this.metrics('none', 0, 0, start, [`unresolved ${resolved.unresolved}`]),
+            };
+        }
+        const permutation = this.choosePermutation(resolved.ids, { objectRange: Boolean(resolved.objectNumericRange) });
+        const compiled = this.compileScanSql(permutation, resolved, options);
+        const matchedRows = this.requireDb()
+            .prepare(compiled.countSql)
+            .get(...compiled.countParams)?.count ?? 0;
+        const rows = this.requireDb().prepare(compiled.sql).all(...compiled.params);
+        return {
+            quads: this.rowsToQuads(rows),
+            metrics: this.metrics(permutation.name, matchedRows, rows.length, start, [
+                `Rdf3xPermutationScan(${permutation.name})`,
+                ...compiled.queryPlan,
+                compiled.sql,
+            ]),
+        };
+    }
+    joinPatterns(patterns, options) {
+        const start = Date.now();
+        if (patterns.length === 0) {
+            return {
+                bindings: [],
+                metrics: this.joinMetrics('none', 0, 0, start, ['Rdf3xJoinBGP(empty)']),
+            };
+        }
+        const compiled = this.compileJoinPatterns(patterns, options);
+        if (compiled.unresolved) {
+            return {
+                bindings: [],
+                metrics: this.joinMetrics('none', 0, 0, start, [
+                    ...compiled.queryPlan,
+                    `unresolved ${compiled.unresolved}`,
+                ]),
+            };
+        }
+        const rows = this.requireDb().prepare(compiled.sql).all(...compiled.params);
+        const matchedRows = compiled.countSql
+            ? this.requireDb().prepare(compiled.countSql).get(...compiled.countParams)?.count ?? 0
+            : rows.length;
+        return {
+            bindings: this.joinRowsToBindings(rows, compiled.variableAliases),
+            metrics: this.joinMetrics(compiled.indexChoice, matchedRows, rows.length, start, [...compiled.queryPlan, compiled.sql]),
+        };
+    }
+    estimateCardinality(pattern) {
+        const resolved = this.resolvePattern(pattern);
+        if (resolved.unresolved) {
+            return {
+                uniqueTriples: 0,
+                matchingQuads: 0,
+                source: 'exact-membership',
+                indexChoice: 'none',
+            };
+        }
+        if (resolved.objectNumericRange) {
+            return this.estimateNumericObjectRangeCardinality(resolved);
+        }
+        if (resolved.ids.graph !== undefined || resolved.graphPrefix !== undefined) {
+            return this.estimateResolvedMembershipCardinality(resolved);
+        }
+        const termIds = TERM_KEYS.filter((key) => resolved.ids[key] !== undefined);
+        const permutation = this.choosePermutation(resolved.ids);
+        if (termIds.length === 3) {
+            return this.estimateExactTriple(resolved.ids, permutation.name);
+        }
+        if (termIds.length === 2) {
+            return this.estimatePairProjection(resolved.ids, permutation.name);
+        }
+        if (termIds.length === 1) {
+            return this.estimateTermProjection(resolved.ids, permutation.name);
+        }
+        return {
+            uniqueTriples: this.rowCount('rdf3x_spo'),
+            matchingQuads: this.rowCount('rdf3x_triple_membership'),
+            source: 'full-count',
+            indexChoice: permutation.name,
+        };
+    }
+    stats() {
+        const spaceObjects = this.collectSpaceObjects();
+        const accountedBytes = spaceObjects.reduce((sum, object) => sum + object.bytes, 0);
+        const databaseBytes = accountedBytes || this.estimateDatabaseBytes();
+        return {
+            uniqueTriples: this.rowCount('rdf3x_spo'),
+            membershipCount: this.rowCount('rdf3x_triple_membership'),
+            graphCount: this.requireDb()
+                .prepare('SELECT COUNT(DISTINCT graph_id) AS count FROM rdf3x_triple_membership')
+                .get()?.count ?? 0,
+            permutationRows: Object.fromEntries(PERMUTATIONS.map((permutation) => [
+                permutation.name,
+                this.rowCount(permutation.table),
+            ])),
+            pairProjectionRows: Object.fromEntries(PAIR_PROJECTIONS.map((projection) => [
+                projection.name,
+                this.rowCount(projection.table),
+            ])),
+            termProjectionRows: Object.fromEntries(TERM_PROJECTIONS.map((projection) => [
+                projection.name,
+                this.rowCount(projection.table),
+            ])),
+            databaseBytes,
+            tableBytes: sumSpaceObjects(spaceObjects, 'table'),
+            indexBytes: sumSpaceObjects(spaceObjects, 'index'),
+            spaceObjects,
+        };
+    }
+    collectSpaceObjects() {
+        const db = this.requireDb();
+        try {
+            const schemaRows = db.prepare(`
+        SELECT name, type, tbl_name
+        FROM sqlite_schema
+        WHERE type IN ('table', 'index')
+          AND (name LIKE 'rdf3x_%' OR tbl_name LIKE 'rdf3x_%')
+      `).all();
+            const schema = new Map(schemaRows.map((row) => [row.name, row]));
+            try {
+                const rows = db.prepare(`
+          SELECT name, COUNT(*) AS pages, SUM(pgsize) AS bytes
+          FROM dbstat
+          WHERE name LIKE 'rdf3x_%'
+             OR name LIKE 'sqlite_autoindex_rdf3x_%'
+          GROUP BY name
+          ORDER BY name
+        `).all();
+                if (rows.length > 0) {
+                    return rows.map((row) => {
+                        const object = schema.get(row.name);
+                        const kind = rdf3xSpaceObjectKind(row.name, object?.type, object?.tbl_name);
+                        return {
+                            name: row.name,
+                            kind,
+                            ...(object?.tbl_name && object.tbl_name !== row.name ? { tableName: object.tbl_name } : {}),
+                            pages: row.pages,
+                            bytes: row.bytes ?? 0,
+                        };
+                    });
+                }
+            }
+            catch {
+                // dbstat is optional in SQLite builds and often unavailable for in-memory databases.
+            }
+            return this.estimateSpaceObjectsFromSchema(schemaRows);
+        }
+        catch {
+            return [];
+        }
+    }
+    initializeSchema() {
+        const permutationTables = PERMUTATIONS.map((permutation) => `
+      CREATE TABLE IF NOT EXISTS ${permutation.table} (
+        ${permutation.columns[0]} INTEGER NOT NULL,
+        ${permutation.columns[1]} INTEGER NOT NULL,
+        ${permutation.columns[2]} INTEGER NOT NULL,
+        PRIMARY KEY (${permutation.columns.join(', ')})
+      );
+    `).join('\n');
+        const pairProjectionTables = PAIR_PROJECTIONS.map((projection) => `
+      CREATE TABLE IF NOT EXISTS ${projection.table} (
+        ${projection.columns[0]} INTEGER NOT NULL,
+        ${projection.columns[1]} INTEGER NOT NULL,
+        triple_count INTEGER NOT NULL,
+        membership_count INTEGER NOT NULL,
+        min_${projection.remainder} INTEGER,
+        max_${projection.remainder} INTEGER,
+        PRIMARY KEY (${projection.columns.join(', ')})
+      );
+    `).join('\n');
+        const termProjectionTables = TERM_PROJECTIONS.map((projection) => `
+      CREATE TABLE IF NOT EXISTS ${projection.table} (
+        ${projection.column} INTEGER NOT NULL PRIMARY KEY,
+        triple_count INTEGER NOT NULL,
+        membership_count INTEGER NOT NULL
+      );
+    `).join('\n');
+        this.requireDb().exec(`
+      CREATE TABLE IF NOT EXISTS rdf3x_triple_membership (
+        graph_id INTEGER NOT NULL,
+        subject_id INTEGER NOT NULL,
+        predicate_id INTEGER NOT NULL,
+        object_id INTEGER NOT NULL,
+        source_file_id INTEGER,
+        source_line_no INTEGER,
+        PRIMARY KEY (graph_id, subject_id, predicate_id, object_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS rdf3x_membership_gspo
+        ON rdf3x_triple_membership(graph_id, subject_id, predicate_id, object_id);
+      CREATE INDEX IF NOT EXISTS rdf3x_membership_spo
+        ON rdf3x_triple_membership(subject_id, predicate_id, object_id);
+      CREATE INDEX IF NOT EXISTS rdf3x_membership_source
+        ON rdf3x_triple_membership(source_file_id);
+
+      ${permutationTables}
+      ${pairProjectionTables}
+      ${termProjectionTables}
+    `);
+    }
+    clearRdf3xTables() {
+        const db = this.requireDb();
+        db.exec([
+            ...PAIR_PROJECTIONS.map((projection) => `DELETE FROM ${projection.table};`),
+            ...TERM_PROJECTIONS.map((projection) => `DELETE FROM ${projection.table};`),
+            'DELETE FROM rdf3x_triple_membership;',
+            ...PERMUTATIONS.map((permutation) => `DELETE FROM ${permutation.table};`),
+        ].join('\n'));
+    }
+    rebuildPairProjection(projection) {
+        const [left, right] = projection.columns;
+        this.requireDb().prepare(`
+      INSERT INTO ${projection.table} (
+        ${left},
+        ${right},
+        triple_count,
+        membership_count,
+        min_${projection.remainder},
+        max_${projection.remainder}
+      )
+      SELECT
+        triple.${left},
+        triple.${right},
+        triple.triple_count,
+        COALESCE(member.membership_count, 0) AS membership_count,
+        triple.min_remainder,
+        triple.max_remainder
+      FROM (
+        SELECT
+          ${left},
+          ${right},
+          COUNT(*) AS triple_count,
+          MIN(${projection.remainder}) AS min_remainder,
+          MAX(${projection.remainder}) AS max_remainder
+        FROM rdf3x_spo
+        GROUP BY ${left}, ${right}
+      ) triple
+      LEFT JOIN (
+        SELECT
+          ${left},
+          ${right},
+          COUNT(*) AS membership_count
+        FROM rdf3x_triple_membership
+        GROUP BY ${left}, ${right}
+      ) member
+        ON member.${left} = triple.${left}
+       AND member.${right} = triple.${right}
+    `).run();
+    }
+    rebuildTermProjection(projection) {
+        this.requireDb().prepare(`
+      INSERT INTO ${projection.table} (
+        ${projection.column},
+        triple_count,
+        membership_count
+      )
+      SELECT
+        triple.${projection.column},
+        triple.triple_count,
+        COALESCE(member.membership_count, 0) AS membership_count
+      FROM (
+        SELECT
+          ${projection.column},
+          COUNT(*) AS triple_count
+        FROM rdf3x_spo
+        GROUP BY ${projection.column}
+      ) triple
+      LEFT JOIN (
+        SELECT
+          ${projection.column},
+          COUNT(*) AS membership_count
+        FROM rdf3x_triple_membership
+        GROUP BY ${projection.column}
+      ) member
+        ON member.${projection.column} = triple.${projection.column}
+    `).run();
+    }
+    compileScanSql(permutation, resolved, options) {
+        const conditions = [];
+        const params = [];
+        const queryPlan = [`Permutation(${permutation.name})`];
+        const ids = resolved.ids;
+        for (const key of TERM_KEYS) {
+            const id = ids[key];
+            if (id === undefined) {
+                continue;
+            }
+            conditions.push(`idx.${TERM_COLUMN[key]} = ?`);
+            params.push(id);
+        }
+        if (ids.graph !== undefined) {
+            conditions.push('membership.graph_id = ?');
+            params.push(ids.graph);
+            queryPlan.push('GraphMembershipFilter');
+        }
+        const graphPrefixJoin = resolved.graphPrefix
+            ? ` JOIN rdf_terms graph_prefix
+          ON graph_prefix.id = membership.graph_id`
+            : '';
+        if (resolved.graphPrefix) {
+            conditions.push(`graph_prefix.kind = ?
+        AND graph_prefix.value >= ?
+        AND graph_prefix.value < ?`);
+            params.push('iri', resolved.graphPrefix, `${resolved.graphPrefix}\uffff`);
+            queryPlan.push('GraphPrefixMembershipFilter');
+        }
+        if (resolved.objectNumericRange) {
+            const range = resolved.objectNumericRange;
+            conditions.push('object_numeric.kind = ?');
+            params.push('literal');
+            if (range.min !== undefined) {
+                conditions.push(`object_numeric.numeric_value ${range.minInclusive ? '>=' : '>'} ?`);
+                params.push(range.min);
+            }
+            if (range.max !== undefined) {
+                conditions.push(`object_numeric.numeric_value ${range.maxInclusive ? '<=' : '<'} ?`);
+                params.push(range.max);
+            }
+            queryPlan.push(`NumericRange(object${range.min !== undefined ? (range.minInclusive ? '$gte' : '$gt') : ''}${range.max !== undefined ? (range.maxInclusive ? '$lte' : '$lt') : ''})`);
+        }
+        const whereClause = conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '';
+        const orderClause = this.buildOrderClause(options);
+        const from = `
+      FROM ${permutation.table} idx
+      JOIN rdf3x_triple_membership membership
+        ON membership.subject_id = idx.subject_id
+       AND membership.predicate_id = idx.predicate_id
+       AND membership.object_id = idx.object_id
+      ${graphPrefixJoin}
+      ${resolved.objectNumericRange ? 'JOIN rdf_terms object_numeric ON object_numeric.id = idx.object_id' : ''}
+    `;
+        const pagination = this.buildPagination(options);
+        return {
+            sql: `
+        SELECT
+          membership.graph_id,
+          idx.subject_id,
+          idx.predicate_id,
+          idx.object_id
+        ${from}
+        ${orderClause.joins}
+        ${whereClause}
+        ${orderClause.orderBy || ` ORDER BY ${permutation.columns.map((column) => `idx.${column}`).join(', ')}, membership.graph_id`}
+        ${pagination.sql}
+      `,
+            params: [...params, ...pagination.params],
+            countSql: `SELECT COUNT(*) AS count ${from} ${whereClause}`,
+            countParams: params,
+            queryPlan: [
+                ...queryPlan,
+                ...(orderClause.orderBy ? [`Rdf3xJoinOrder(${(options?.order ?? []).map((entry, index) => `${options?.reverse ? 'desc' : 'asc'}:${entry}:${index}`).join(',')})`] : []),
+                ...(pagination.sql ? ['Pagination'] : []),
+            ],
+        };
+    }
+    compileJoinPatterns(patterns, options) {
+        const sources = patterns.map((entry, inputIndex) => {
+            const resolved = this.resolveJoinPattern(entry.pattern);
+            const permutation = this.choosePermutation(resolved.ids, { objectRange: Boolean(resolved.objectNumericRange) });
+            const estimate = resolved.unresolved
+                ? {
+                    uniqueTriples: 0,
+                    matchingQuads: 0,
+                    source: 'full-count',
+                    indexChoice: 'none',
+                }
+                : this.estimateResolvedCardinality(resolved);
+            return {
+                inputIndex,
+                alias: `q${inputIndex}`,
+                membershipAlias: `m${inputIndex}`,
+                entry,
+                resolved,
+                permutation,
+                estimate,
+            };
+        });
+        const startPattern = this.chooseJoinStart(sources);
+        const orderedSources = [startPattern, ...sources.filter((source) => source.inputIndex !== startPattern.inputIndex)];
+        const queryPlan = [
+            `Rdf3xJoinBGP(${patterns.length})`,
+            `Rdf3xJoinOrder(${orderedSources.map((source) => `?${source.inputIndex}:${source.estimate.indexChoice}`).join('>')})`,
+        ];
+        const variableColumns = new Map();
+        const variableAliases = new Map();
+        const conditions = [];
+        const params = [];
+        const countParams = [];
+        const indexChoices = [];
+        const fromFragments = [];
+        for (const [position, source] of orderedSources.entries()) {
+            const scanSql = this.joinSourceSql(source, position === 0);
+            if (source.resolved.unresolved) {
+                return {
+                    sql: '',
+                    params: [],
+                    countParams: [],
+                    indexChoice: 'none',
+                    queryPlan,
+                    variableColumns,
+                    variableAliases,
+                    unresolved: source.resolved.unresolved,
+                };
+            }
+            fromFragments.push(scanSql.from);
+            conditions.push(...scanSql.conditions);
+            params.push(...scanSql.params);
+            countParams.push(...scanSql.params);
+            queryPlan.push(...scanSql.queryPlan);
+            indexChoices.push(source.estimate.indexChoice);
+            for (const key of ['graph', ...TERM_KEYS]) {
+                const variableName = source.entry.variables[key];
+                if (!variableName) {
+                    continue;
+                }
+                const column = key === 'graph'
+                    ? `${source.membershipAlias}.graph_id`
+                    : `${source.alias}.${TERM_COLUMN[key]}`;
+                const existing = variableColumns.get(variableName);
+                if (existing) {
+                    conditions.push(`${existing} = ${column}`);
+                }
+                else {
+                    variableColumns.set(variableName, column);
+                }
+            }
+        }
+        const projectVariables = options?.project ?? [...variableColumns.keys()];
+        const projectionColumns = projectVariables.map((variableName) => {
+            const column = variableColumns.get(variableName);
+            if (!column) {
+                throw new Error(`Rdf3x BGP join cannot project unbound variable: ${variableName}`);
+            }
+            const alias = `v${variableAliases.size}`;
+            variableAliases.set(variableName, alias);
+            return `${column} AS ${alias}`;
+        });
+        const projection = projectionColumns.length > 0
+            ? `${options?.distinct ? 'DISTINCT ' : ''}${projectionColumns.join(', ')}`
+            : `${options?.distinct ? 'DISTINCT ' : ''}1 AS __empty`;
+        const orderClause = this.buildJoinOrderClause(options, variableColumns);
+        const whereClause = conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '';
+        const from = fromFragments.join('');
+        let sql = `SELECT ${projection} FROM ${from}${orderClause.joins}${whereClause}${orderClause.orderBy}`;
+        const sqlParams = [...params];
+        const paginated = options?.limit !== undefined || options?.offset !== undefined;
+        const countMatchedRows = options?.countMatchedRows ?? true;
+        if (options?.limit !== undefined) {
+            sql += ' LIMIT ?';
+            sqlParams.push(options.limit);
+        }
+        if (options?.offset !== undefined) {
+            if (options.limit === undefined) {
+                sql += ' LIMIT -1';
+            }
+            sql += ' OFFSET ?';
+            sqlParams.push(options.offset);
+        }
+        if (orderClause.orderBy) {
+            queryPlan.push(`Rdf3xJoinOrderBy(${(options?.orderBy ?? []).map((entry) => `${entry.direction ?? 'asc'}:${entry.variable}`).join(',')})`);
+        }
+        if (options?.distinct) {
+            queryPlan.push(`Rdf3xJoinDistinct(${projectVariables.map((variableName) => `?${variableName}`).join(',')})`);
+        }
+        if (paginated) {
+            queryPlan.push('Rdf3xJoinLimit');
+        }
+        return {
+            sql,
+            params: sqlParams,
+            countSql: paginated && countMatchedRows ? `SELECT COUNT(*) AS count FROM ${from}${orderClause.joins}${whereClause}` : undefined,
+            countParams,
+            indexChoice: `Rdf3xJoinBGP(${indexChoices.join('>')})`,
+            queryPlan,
+            variableColumns,
+            variableAliases,
+        };
+    }
+    joinSourceSql(source, first) {
+        const conditions = [];
+        const params = [];
+        const queryPlan = [`Rdf3xPermutationScan(${source.permutation.name})`];
+        const alias = source.alias;
+        const graphPrefixAlias = `${source.membershipAlias}_graph_prefix`;
+        for (const key of TERM_KEYS) {
+            const id = source.resolved.ids[key];
+            if (id === undefined) {
+                continue;
+            }
+            conditions.push(`${alias}.${TERM_COLUMN[key]} = ?`);
+            params.push(id);
+        }
+        let from = first
+            ? `${source.permutation.table} ${alias}
+        JOIN rdf3x_triple_membership ${source.membershipAlias}
+          ON ${source.membershipAlias}.subject_id = ${alias}.subject_id
+         AND ${source.membershipAlias}.predicate_id = ${alias}.predicate_id
+         AND ${source.membershipAlias}.object_id = ${alias}.object_id`
+            : ` JOIN ${source.permutation.table} ${alias}
+          ON 1 = 1
+        JOIN rdf3x_triple_membership ${source.membershipAlias}
+          ON ${source.membershipAlias}.subject_id = ${alias}.subject_id
+         AND ${source.membershipAlias}.predicate_id = ${alias}.predicate_id
+         AND ${source.membershipAlias}.object_id = ${alias}.object_id`;
+        if (source.resolved.ids.graph !== undefined) {
+            conditions.push(`${source.membershipAlias}.graph_id = ?`);
+            params.push(source.resolved.ids.graph);
+            queryPlan.push('GraphMembershipFilter');
+        }
+        if (source.resolved.graphPrefix !== undefined) {
+            from += ` JOIN rdf_terms ${graphPrefixAlias}
+          ON ${graphPrefixAlias}.id = ${source.membershipAlias}.graph_id`;
+            conditions.push(`${graphPrefixAlias}.kind = ?
+        AND ${graphPrefixAlias}.value >= ?
+        AND ${graphPrefixAlias}.value < ?`);
+            params.push('iri', source.resolved.graphPrefix, `${source.resolved.graphPrefix}\uffff`);
+            queryPlan.push('GraphPrefixMembershipFilter');
+        }
+        if (source.resolved.objectNumericRange) {
+            from += ` JOIN rdf_terms ${source.alias}_object_numeric
+          ON ${source.alias}_object_numeric.id = ${source.alias}.object_id`;
+            const range = source.resolved.objectNumericRange;
+            conditions.push(`${source.alias}_object_numeric.kind = ?`);
+            params.push('literal');
+            if (range.min !== undefined) {
+                conditions.push(`${source.alias}_object_numeric.numeric_value ${range.minInclusive ? '>=' : '>'} ?`);
+                params.push(range.min);
+            }
+            if (range.max !== undefined) {
+                conditions.push(`${source.alias}_object_numeric.numeric_value ${range.maxInclusive ? '<=' : '<'} ?`);
+                params.push(range.max);
+            }
+            queryPlan.push(`NumericRange(object${range.min !== undefined ? (range.minInclusive ? '$gte' : '$gt') : ''}${range.max !== undefined ? (range.maxInclusive ? '$lte' : '$lt') : ''})`);
+        }
+        return {
+            from,
+            conditions,
+            params,
+            queryPlan,
+        };
+    }
+    buildJoinOrderClause(options, variableColumns) {
+        if (!options?.orderBy || options.orderBy.length === 0) {
+            return { joins: '', orderBy: '' };
+        }
+        const joins = options.orderBy.map((entry, index) => {
+            const column = variableColumns.get(entry.variable);
+            if (!column) {
+                throw new Error(`Rdf3x join cannot order by unbound variable: ${entry.variable}`);
+            }
+            const alias = `join_order_t${index}`;
+            return {
+                join: ` JOIN rdf_terms ${alias} ON ${alias}.id = ${column}`,
+                order: `${alias}.value${entry.direction === 'desc' ? ' DESC' : ''}`,
+            };
+        });
+        return {
+            joins: joins.map((entry) => entry.join).join(''),
+            orderBy: ` ORDER BY ${joins.map((entry) => entry.order).join(', ')}`,
+        };
+    }
+    buildOrderClause(options) {
+        if (!options?.order || options.order.length === 0) {
+            return { joins: '', orderBy: '' };
+        }
+        const joins = options.order.map((termName, index) => {
+            const column = ORDER_COLUMN[termName];
+            const alias = `order_t${index}`;
+            const direction = options.reverse ? ' DESC' : '';
+            return {
+                join: ` JOIN rdf_terms ${alias} ON ${alias}.id = idx.${column}`,
+                order: `${alias}.value${direction}`,
+            };
+        });
+        return {
+            joins: joins.map((entry) => entry.join).join(''),
+            orderBy: ` ORDER BY ${joins.map((entry) => entry.order).join(', ')}`,
+        };
+    }
+    chooseJoinStart(sources) {
+        if (sources.length === 0) {
+            throw new Error('Rdf3x join requires at least one source');
+        }
+        return [...sources].sort((left, right) => this.compareJoinSources(left, right))[0];
+    }
+    compareJoinSources(left, right) {
+        const leftResolved = left.resolved.unresolved ? Number.POSITIVE_INFINITY : left.estimate.matchingQuads;
+        const rightResolved = right.resolved.unresolved ? Number.POSITIVE_INFINITY : right.estimate.matchingQuads;
+        if (leftResolved !== rightResolved) {
+            return leftResolved - rightResolved;
+        }
+        if (left.estimate.uniqueTriples !== right.estimate.uniqueTriples) {
+            return left.estimate.uniqueTriples - right.estimate.uniqueTriples;
+        }
+        return left.inputIndex - right.inputIndex;
+    }
+    estimateResolvedCardinality(resolved) {
+        const ids = resolved.ids;
+        if (resolved.objectNumericRange) {
+            return this.estimateNumericObjectRangeCardinality(resolved);
+        }
+        const termIds = TERM_KEYS.filter((key) => ids[key] !== undefined);
+        if (ids.graph !== undefined || resolved.graphPrefix !== undefined) {
+            return this.estimateResolvedMembershipCardinality(resolved);
+        }
+        if (termIds.length === 3) {
+            return this.estimateExactTriple(ids, this.choosePermutation(ids).name);
+        }
+        if (termIds.length === 2) {
+            return this.estimatePairProjection(ids, this.choosePermutation(ids).name);
+        }
+        if (termIds.length === 1) {
+            return this.estimateTermProjection(ids, this.choosePermutation(ids).name);
+        }
+        return {
+            uniqueTriples: this.rowCount('rdf3x_spo'),
+            matchingQuads: this.rowCount('rdf3x_triple_membership'),
+            source: 'full-count',
+            indexChoice: this.choosePermutation(ids, { objectRange: Boolean(resolved.objectNumericRange) }).name,
+        };
+    }
+    resolveJoinPattern(pattern) {
+        const ids = {};
+        let graphPrefix;
+        let objectNumericRange;
+        for (const key of ['graph', ...TERM_KEYS]) {
+            const match = pattern[key];
+            if (!match) {
+                continue;
+            }
+            if (key === 'graph' && isGraphPrefixPattern(match)) {
+                graphPrefix = match.$startsWith;
+                continue;
+            }
+            if (key === 'object' && isNumericObjectRangePattern(match)) {
+                const resolvedRange = this.resolveNumericObjectRange(match);
+                if (!resolvedRange) {
+                    return { ids, graphPrefix, objectNumericRange: resolvedRange, unresolved: key };
+                }
+                objectNumericRange = resolvedRange;
+                continue;
+            }
+            if (!isRdfTerm(match)) {
+                return { ids, graphPrefix, unresolved: key };
+            }
+            const id = this.requireDictionary().find(match);
+            if (id === undefined) {
+                return { ids, graphPrefix, unresolved: key };
+            }
+            ids[key] = id;
+        }
+        return {
+            ids,
+            ...(graphPrefix !== undefined ? { graphPrefix } : {}),
+            ...(objectNumericRange !== undefined ? { objectNumericRange } : {}),
+        };
+    }
+    joinMetrics(indexChoice, matchedRows, returnedRows, start, queryPlan) {
+        return {
+            engine: 'solid-rdf3x',
+            indexChoice,
+            matchedRows,
+            returnedRows,
+            durationMs: Date.now() - start,
+            queryPlan,
+        };
+    }
+    joinRowsToBindings(rows, variableAliases) {
+        const aliases = [...variableAliases.entries()];
+        const termMap = this.requireDictionary().rowsForIds(rows.flatMap((row) => (aliases
+            .map(([, alias]) => row[alias])
+            .filter((id) => typeof id === 'number'))));
+        return rows.map((row) => {
+            const binding = {};
+            for (const [variableName, alias] of aliases) {
+                const id = row[alias];
+                if (typeof id !== 'number') {
+                    continue;
+                }
+                binding[variableName] = requiredTerm(termMap, id);
+            }
+            return binding;
+        });
+    }
+    buildPagination(options) {
+        if (!options) {
+            return { sql: '', params: [] };
+        }
+        const clauses = [];
+        const params = [];
+        if (options.limit !== undefined) {
+            clauses.push('LIMIT ?');
+            params.push(Math.max(0, options.limit));
+        }
+        if (options.offset !== undefined) {
+            if (options.limit === undefined) {
+                clauses.push('LIMIT -1');
+            }
+            clauses.push('OFFSET ?');
+            params.push(Math.max(0, options.offset));
+        }
+        return {
+            sql: clauses.length > 0 ? ` ${clauses.join(' ')}` : '',
+            params,
+        };
+    }
+    estimateExactTriple(ids, indexChoice) {
+        const row = this.requireDb().prepare(`
+      SELECT COUNT(*) AS count
+      FROM rdf3x_spo
+      WHERE subject_id = ?
+        AND predicate_id = ?
+        AND object_id = ?
+    `).get(ids.subject, ids.predicate, ids.object);
+        const membership = this.requireDb().prepare(`
+      SELECT COUNT(*) AS count
+      FROM rdf3x_triple_membership
+      WHERE subject_id = ?
+        AND predicate_id = ?
+        AND object_id = ?
+    `).get(ids.subject, ids.predicate, ids.object);
+        return {
+            uniqueTriples: row?.count ?? 0,
+            matchingQuads: membership?.count ?? 0,
+            source: 'exact-triple',
+            indexChoice,
+        };
+    }
+    estimatePairProjection(ids, indexChoice) {
+        const projection = this.pairProjectionFor(ids);
+        if (!projection) {
+            return this.estimateMembershipCardinality(ids);
+        }
+        const [left, right] = projection.columns;
+        const row = this.requireDb().prepare(`
+      SELECT triple_count, membership_count
+      FROM ${projection.table}
+      WHERE ${left} = ?
+        AND ${right} = ?
+    `).get(ids[keyForColumn(left)], ids[keyForColumn(right)]);
+        return {
+            uniqueTriples: row?.triple_count ?? 0,
+            matchingQuads: row?.membership_count ?? 0,
+            source: 'projection-stat',
+            indexChoice,
+        };
+    }
+    estimateTermProjection(ids, indexChoice) {
+        const key = TERM_KEYS.find((candidate) => ids[candidate] !== undefined);
+        if (!key) {
+            return this.estimateMembershipCardinality(ids);
+        }
+        const projection = TERM_PROJECTIONS.find((candidate) => candidate.column === TERM_COLUMN[key]);
+        if (!projection) {
+            return this.estimateMembershipCardinality(ids);
+        }
+        const row = this.requireDb().prepare(`
+      SELECT triple_count, membership_count
+      FROM ${projection.table}
+      WHERE ${projection.column} = ?
+    `).get(ids[key]);
+        return {
+            uniqueTriples: row?.triple_count ?? 0,
+            matchingQuads: row?.membership_count ?? 0,
+            source: 'term-stat',
+            indexChoice,
+        };
+    }
+    estimateMembershipCardinality(ids) {
+        return this.estimateResolvedMembershipCardinality({ ids });
+    }
+    estimateResolvedMembershipCardinality(resolved) {
+        const { joins, whereClause, params } = this.buildMembershipWhere(resolved);
+        const matchingQuads = this.requireDb().prepare(`
+      SELECT COUNT(*) AS count
+      FROM rdf3x_triple_membership
+      ${joins}
+      ${whereClause}
+    `).get(...params)?.count ?? 0;
+        const uniqueTriples = this.requireDb().prepare(`
+      SELECT COUNT(*) AS count
+      FROM (
+        SELECT DISTINCT subject_id, predicate_id, object_id
+        FROM rdf3x_triple_membership
+        ${joins}
+        ${whereClause}
+      ) distinct_triples
+    `).get(...params)?.count ?? 0;
+        return {
+            uniqueTriples,
+            matchingQuads,
+            source: 'exact-membership',
+            indexChoice: 'source-membership',
+        };
+    }
+    buildMembershipWhere(resolved) {
+        const ids = resolved.ids;
+        const conditions = [];
+        const params = [];
+        for (const key of ['graph', ...TERM_KEYS]) {
+            const id = ids[key];
+            if (id === undefined) {
+                continue;
+            }
+            conditions.push(`${PATTERN_COLUMNS[key]} = ?`);
+            params.push(id);
+        }
+        const joins = resolved.graphPrefix !== undefined
+            ? ` JOIN rdf_terms membership_graph_prefix
+          ON membership_graph_prefix.id = rdf3x_triple_membership.graph_id`
+            : '';
+        if (resolved.graphPrefix !== undefined) {
+            conditions.push(`membership_graph_prefix.kind = ?
+        AND membership_graph_prefix.value >= ?
+        AND membership_graph_prefix.value < ?`);
+            params.push('iri', resolved.graphPrefix, `${resolved.graphPrefix}\uffff`);
+        }
+        return {
+            whereClause: conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '',
+            joins,
+            params,
+        };
+    }
+    pairProjectionFor(ids) {
+        const columns = TERM_KEYS
+            .filter((key) => ids[key] !== undefined)
+            .map((key) => TERM_COLUMN[key]);
+        return PAIR_PROJECTIONS.find((projection) => (projection.columns.every((column) => columns.includes(column))));
+    }
+    resolvePattern(pattern) {
+        const ids = {};
+        let graphPrefix;
+        let objectNumericRange;
+        for (const key of ['graph', ...TERM_KEYS]) {
+            const term = pattern[key];
+            if (!term) {
+                continue;
+            }
+            if (key === 'graph' && isGraphPrefixPattern(term)) {
+                graphPrefix = term.$startsWith;
+                continue;
+            }
+            if (key === 'object' && isNumericObjectRangePattern(term)) {
+                const resolvedRange = this.resolveNumericObjectRange(term);
+                if (!resolvedRange) {
+                    return { ids, graphPrefix, objectNumericRange: resolvedRange, unresolved: key };
+                }
+                objectNumericRange = resolvedRange;
+                continue;
+            }
+            if (key === 'graph' && !isRdfTerm(term)) {
+                return { ids, graphPrefix, unresolved: key };
+            }
+            if (key !== 'graph' && !isRdfTerm(term)) {
+                return { ids, graphPrefix, unresolved: key };
+            }
+            const rdfTerm = term;
+            const id = this.requireDictionary().find(rdfTerm);
+            if (id === undefined) {
+                return { ids, graphPrefix, unresolved: key };
+            }
+            ids[key] = id;
+        }
+        return {
+            ids,
+            ...(graphPrefix !== undefined ? { graphPrefix } : {}),
+            ...(objectNumericRange !== undefined ? { objectNumericRange } : {}),
+        };
+    }
+    estimateNumericObjectRangeCardinality(resolved) {
+        const range = resolved.objectNumericRange;
+        if (!range) {
+            return this.estimateMembershipCardinality(resolved.ids);
+        }
+        const { joins, whereClause, params } = this.buildMembershipWhere({
+            ids: resolved.ids,
+            ...(resolved.graphPrefix !== undefined ? { graphPrefix: resolved.graphPrefix } : {}),
+        });
+        const numericConditions = ['object_numeric.kind = ?'];
+        const numericParams = ['literal'];
+        if (range.min !== undefined) {
+            numericConditions.push(`object_numeric.numeric_value ${range.minInclusive ? '>=' : '>'} ?`);
+            numericParams.push(range.min);
+        }
+        if (range.max !== undefined) {
+            numericConditions.push(`object_numeric.numeric_value ${range.maxInclusive ? '<=' : '<'} ?`);
+            numericParams.push(range.max);
+        }
+        const membershipWhere = whereClause
+            ? `${whereClause} AND ${numericConditions.join(' AND ')}`
+            : ` WHERE ${numericConditions.join(' AND ')}`;
+        const matchingQuads = this.requireDb().prepare(`
+      SELECT COUNT(*) AS count
+      FROM rdf3x_triple_membership
+      ${joins}
+      JOIN rdf_terms object_numeric ON object_numeric.id = rdf3x_triple_membership.object_id
+      ${membershipWhere}
+    `).get(...params, ...numericParams)?.count ?? 0;
+        const uniqueTriples = this.requireDb().prepare(`
+      SELECT COUNT(*) AS count
+      FROM (
+        SELECT DISTINCT subject_id, predicate_id, object_id
+        FROM rdf3x_triple_membership
+        ${joins}
+        JOIN rdf_terms object_numeric ON object_numeric.id = rdf3x_triple_membership.object_id
+        ${membershipWhere}
+      ) distinct_triples
+    `).get(...params, ...numericParams)?.count ?? 0;
+        return {
+            uniqueTriples,
+            matchingQuads,
+            source: 'exact-membership',
+            indexChoice: 'source-membership',
+        };
+    }
+    resolveNumericObjectRange(match) {
+        const range = {};
+        let hasRange = false;
+        for (const [operator, inclusive] of [
+            ['$gt', false],
+            ['$gte', true],
+            ['$lt', false],
+            ['$lte', true],
+        ]) {
+            const value = match[operator];
+            if (value === undefined) {
+                continue;
+            }
+            hasRange = true;
+            const numericValue = this.numericValueForPattern(value);
+            if (numericValue === undefined) {
+                return undefined;
+            }
+            if (operator === '$gt' || operator === '$gte') {
+                range.min = numericValue;
+                range.minInclusive = inclusive;
+            }
+            else {
+                range.max = numericValue;
+                range.maxInclusive = inclusive;
+            }
+        }
+        return hasRange ? range : undefined;
+    }
+    numericValueForPattern(value) {
+        if (typeof value === 'number') {
+            return Number.isFinite(value) ? value : undefined;
+        }
+        if (typeof value === 'string') {
+            const parsed = Number(value);
+            return Number.isFinite(parsed) ? parsed : undefined;
+        }
+        if (value.termType !== 'Literal' || !(0, RdfTermSemantics_1.isRdfNumericDatatype)(value.datatype.value)) {
+            return undefined;
+        }
+        const parsed = (0, RdfTermSemantics_1.rdfNumericValue)(value.value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    choosePermutation(ids, constraints) {
+        const has = (key) => ids[key] !== undefined;
+        const hasObjectConstraint = has('object') || Boolean(constraints?.objectRange);
+        if (has('subject') && has('predicate'))
+            return this.permutation('SPO');
+        if (has('subject') && hasObjectConstraint)
+            return this.permutation('SOP');
+        if (has('predicate') && has('subject'))
+            return this.permutation('PSO');
+        if (has('predicate') && hasObjectConstraint)
+            return this.permutation('POS');
+        if (hasObjectConstraint && has('subject'))
+            return this.permutation('OSP');
+        if (hasObjectConstraint && has('predicate'))
+            return this.permutation('OPS');
+        if (has('subject'))
+            return this.permutation('SPO');
+        if (has('predicate'))
+            return this.permutation('PSO');
+        if (hasObjectConstraint)
+            return this.permutation('OSP');
+        return this.permutation('SPO');
+    }
+    permutation(name) {
+        const permutation = PERMUTATIONS.find((candidate) => candidate.name === name);
+        if (!permutation) {
+            throw new Error(`Unknown RDF-3X permutation: ${name}`);
+        }
+        return permutation;
+    }
+    rowsToQuads(rows) {
+        const termMap = this.requireDictionary().rowsForIds(rows.flatMap((row) => [
+            row.graph_id,
+            row.subject_id,
+            row.predicate_id,
+            row.object_id,
+        ]));
+        return rows.map((row) => n3_1.DataFactory.quad(requiredTerm(termMap, row.subject_id), requiredTerm(termMap, row.predicate_id), requiredTerm(termMap, row.object_id), requiredTerm(termMap, row.graph_id)));
+    }
+    rowCount(table) {
+        return this.requireDb().prepare(`SELECT COUNT(*) AS count FROM ${table}`).get()?.count ?? 0;
+    }
+    collectPageCount() {
+        try {
+            return this.requireDb().prepare('PRAGMA page_count').get()?.page_count ?? 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    estimateDatabaseBytes() {
+        const pageSize = this.estimatePageSize();
+        const pageCount = this.collectPageCount();
+        return pageSize * pageCount;
+    }
+    estimateSpaceObjectsFromSchema(schemaRows) {
+        const pageSize = this.estimatePageSize();
+        return schemaRows.map((object) => ({
+            name: object.name,
+            kind: rdf3xSpaceObjectKind(object.name, object.type, object.tbl_name),
+            ...(object.tbl_name && object.tbl_name !== object.name ? { tableName: object.tbl_name } : {}),
+            pages: 1,
+            bytes: pageSize,
+            estimated: true,
+        }));
+    }
+    estimatePageSize() {
+        try {
+            return this.requireDb().prepare('PRAGMA page_size').get()?.page_size ?? 4096;
+        }
+        catch {
+            return 4096;
+        }
+    }
+    metrics(indexChoice, matchedRows, returnedRows, start, queryPlan) {
+        return {
+            engine: 'solid-rdf3x',
+            indexChoice,
+            matchedRows,
+            returnedRows,
+            durationMs: Date.now() - start,
+            queryPlan,
+        };
+    }
+    requireDb() {
+        if (!this.db) {
+            throw new Error('Rdf3xTripleIndex is not open');
+        }
+        return this.db;
+    }
+    requireDictionary() {
+        if (!this.dictionary) {
+            throw new Error('Rdf3xTripleIndex is not open');
+        }
+        return this.dictionary;
+    }
+}
+exports.Rdf3xTripleIndex = Rdf3xTripleIndex;
+function keyForColumn(column) {
+    if (column === 'subject_id')
+        return 'subject';
+    if (column === 'predicate_id')
+        return 'predicate';
+    return 'object';
+}
+function requiredTerm(termMap, id) {
+    const term = termMap.get(id);
+    if (!term) {
+        throw new Error(`RDF term not found while reading RDF-3X index: ${id}`);
+    }
+    return term;
+}
+function isRdfTerm(value) {
+    return value !== null && typeof value === 'object' && 'termType' in value;
+}
+function pairProjectionRowTotal(rows) {
+    return Object.values(rows).reduce((sum, count) => sum + count, 0);
+}
+function termProjectionRowTotal(rows) {
+    return Object.values(rows).reduce((sum, count) => sum + count, 0);
+}
+function sumSpaceObjects(objects, kind) {
+    return objects
+        .filter((object) => object.kind === kind)
+        .reduce((sum, object) => sum + object.bytes, 0);
+}
+function rdf3xSpaceObjectKind(name, schemaType, tableName) {
+    if (schemaType === 'table' && name.startsWith('rdf3x_')) {
+        return 'table';
+    }
+    if (schemaType === 'index' && (name.startsWith('rdf3x_') || tableName?.startsWith('rdf3x_'))) {
+        return 'index';
+    }
+    if (name.startsWith('sqlite_')) {
+        return 'internal';
+    }
+    return 'unknown';
+}
+function isGraphPrefixPattern(value) {
+    return value !== null
+        && typeof value === 'object'
+        && '$startsWith' in value
+        && typeof value.$startsWith === 'string';
+}
+function isNumericObjectRangePattern(value) {
+    return value !== null
+        && typeof value === 'object'
+        && !('termType' in value)
+        && ['$gt', '$gte', '$lt', '$lte'].some((operator) => operator in value);
+}
+//# sourceMappingURL=Rdf3xTripleIndex.js.map