@carbonorm/carbonnode 3.10.0 → 3.11.0

package/src/__tests__/sakila-db/C6.js

@@ -1342,7 +1342,7 @@ export const TABLES = {
 };
 export const C6 = {
     ...C6Constants,
-    C6VERSION: '3.10.0',
+    C6VERSION: '3.11.0',
     IMPORT: async (tableName) => {
         tableName = tableName.toLowerCase();
         // if tableName is not a key in the TABLES object then throw an error

package/src/__tests__/sakila-db/C6.ts

@@ -2009,7 +2009,7 @@ export type RestTableInterfaces = iActor
 
 export const C6 : iC6Object<RestTableInterfaces> = {
     ...C6Constants,
-    C6VERSION: '3.10.0',
+    C6VERSION: '3.11.0',
     IMPORT: async (tableName: string) : Promise<iDynamicApiImport> => {
 
         tableName = tableName.toLowerCase();

package/src/__tests__/sqlBuilders.complex.test.ts

@@ -9,6 +9,7 @@ const Property_Units = {
   UNIT_ID: 'property_units.unit_id',
   LOCATION: 'property_units.location',
   PARCEL_ID: 'property_units.parcel_id',
+  COUNTY_ID: 'property_units.county_id',
 } as const;
 
 const Parcel_Sales = {
@@ -19,6 +20,13 @@ const Parcel_Sales = {
   SALE_DATE: 'parcel_sales.sale_date',
 } as const;
 
+const Parcel_Building_Details = {
+  TABLE_NAME: 'parcel_building_details',
+  PARCEL_ID: 'parcel_building_details.parcel_id',
+  YEAR_BUILT: 'parcel_building_details.year_built',
+  GLA: 'parcel_building_details.gla',
+} as const;
+
 /**
  * Complex SELECT coverage focused on WHERE operators, JOIN chains, ORDER, and pagination.
  */
@@ -479,4 +487,81 @@ describe('SQL Builders - Complex SELECTs', () => {
     expect(sql).toContain('WHERE ( property_units.unit_id IN (SELECT parcel_sales.parcel_id');
     expect(params).toContain(5000);
   });
+
+  it('serializes spatial filtering with FORCE INDEX and correlated EXISTS subqueries', () => {
+    const config = buildParcelConfig();
+    const polygon = 'POLYGON((39.5185659 -105.0142915, 39.5401859 -105.0142915, 39.5401859 -104.9862115, 39.5185659 -104.9862115, 39.5185659 -105.0142915))';
+    const point = [C6C.ST_GEOMFROMTEXT, ['POINT(39.5293759 -105.0002515)', 4326]];
+    const unitId = Buffer.from('11F0615D24861BE1ADD40AFFCF6A1F27', 'hex');
+    const countyId = Buffer.from('11F012CFF561A29DBB0E0AFFF25F1747', 'hex');
+
+    const qb = new SelectQueryBuilder(config as any, {
+      [C6C.SELECT]: ['property_units.*'],
+      [C6C.INDEX_HINTS]: {
+        [C6C.FORCE_INDEX]: ['idx_county_id', 'idx_property_units_location'],
+      },
+      [C6C.WHERE]: {
+        [Property_Units.UNIT_ID]: [C6C.NOT_EQUAL, unitId],
+        [Property_Units.COUNTY_ID]: countyId,
+        [C6C.MBRCONTAINS]: [
+          [C6C.ST_GEOMFROMTEXT, [polygon, 4326]],
+          Property_Units.LOCATION,
+        ],
+        [C6C.LESS_THAN_OR_EQUAL_TO]: [
+          [C6C.ST_DISTANCE_SPHERE, Property_Units.LOCATION, point],
+          1200,
+        ],
+        [C6C.EXISTS]: [
+          [
+            Property_Units.PARCEL_ID,
+            {
+              [C6C.SUBSELECT]: {
+                [C6C.SELECT]: [Parcel_Building_Details.PARCEL_ID],
+                [C6C.FROM]: Parcel_Building_Details.TABLE_NAME,
+                [C6C.WHERE]: {
+                  [Parcel_Building_Details.YEAR_BUILT]: [C6C.BETWEEN, [1988, 2008]],
+                  [Parcel_Building_Details.GLA]: [C6C.BETWEEN, [1876.5, 3127.5]],
+                },
+              },
+            },
+          ],
+          [
+            Property_Units.PARCEL_ID,
+            {
+              [C6C.SUBSELECT]: {
+                [C6C.SELECT]: [Parcel_Sales.PARCEL_ID],
+                [C6C.FROM]: Parcel_Sales.TABLE_NAME,
+                [C6C.WHERE]: {
+                  [Parcel_Sales.SALE_DATE]: [C6C.BETWEEN, ['2023-01-01', '2024-06-30']],
+                  [Parcel_Sales.SALE_PRICE]: [C6C.NOT_EQUAL, 0],
+                },
+              },
+            },
+          ],
+        ],
+      },
+      [C6C.PAGINATION]: {
+        [C6C.LIMIT]: 100,
+        [C6C.ORDER]: {
+          [C6C.ST_DISTANCE_SPHERE]: [Property_Units.LOCATION, point],
+        },
+      },
+    } as any, false);
+
+    const { sql, params } = qb.build(Property_Units.TABLE_NAME);
+
+    expect(sql).toContain('FORCE INDEX (`idx_county_id`, `idx_property_units_location`)');
+    expect(sql).toMatch(/MBRCONTAINS\(ST_GEOMFROMTEXT\('POLYGON\(\(39\.5185659 -105\.0142915, 39\.5401859 -105\.0142915, 39\.5401859 -104\.9862115, 39\.5185659 -104\.9862115, 39\.5185659 -105\.0142915\)\)', 4326\), property_units\.location\)/);
+    expect(sql).toMatch(/ST_DISTANCE_SPHERE\(property_units\.location, ST_GEOMFROMTEXT\('POINT\(39\.5293759 -105\.0002515\)', 4326\)\) <= \?/);
+    expect(sql).toMatch(/\(parcel_building_details\.parcel_id\) = property_units\.parcel_id/);
+    expect(sql).toMatch(/\(parcel_sales\.parcel_id\) = property_units\.parcel_id/);
+    expect(sql).toMatch(/ORDER BY ST[_]Distance[_]Sphere\(property_units\.location, ST_GEOMFROMTEXT\('POINT\(39\.5293759 -105\.0002515\)', 4326\)\)/i);
+
+    expect(params).toHaveLength(10);
+    expect(params[0]).toEqual(unitId);
+    expect(params[1]).toEqual(countyId);
+    expect(params).toContain(1200);
+    expect(params.slice(3, 7)).toEqual([1988, 2008, 1876.5, 3127.5]);
+    expect(params.slice(7)).toEqual(['2023-01-01', '2024-06-30', 0]);
+  });
 });

package/src/api/C6Constants.ts

@@ -1,6 +1,4 @@
-
 export const C6Constants = {
-
     // try to 1=1 match the Rest abstract class
     ADDDATE: 'ADDDATE',
     ADDTIME: 'ADDTIME',
@@ -34,11 +32,13 @@ export const C6Constants = {
     DESC: 'DESC',
     DISTINCT: 'DISTINCT',
 
+    EXISTS: 'EXISTS',
     EXTRACT: 'EXTRACT',
     EQUAL: '=',
     EQUAL_NULL_SAFE: '<=>',
 
     FALSE: 'FALSE',
+    FORCE: 'FORCE',
     FULL_OUTER: 'FULL_OUTER',
     FROM_DAYS: 'FROM_DAYS',
     FROM_UNIXTIME: 'FROM_UNIXTIME',
@@ -57,6 +57,7 @@ export const C6Constants = {
     HOUR_MINUTE: 'HOUR_MINUTE',
 
     IN: 'IN',
+    INDEX: 'INDEX',
     IS: 'IS',
     IS_NOT: 'IS_NOT',
     INNER: 'INNER',
@@ -77,6 +78,7 @@ export const C6Constants = {
     MAKEDATE: 'MAKEDATE',
     MAKETIME: 'MAKETIME',
     MATCH_AGAINST: 'MATCH_AGAINST',
+    MBRCONTAINS: 'MBRContains',
     MONTHNAME: 'MONTHNAME',
     MICROSECOND: 'MICROSECOND',
     MINUTE: 'MINUTE',
@@ -95,8 +97,16 @@ export const C6Constants = {
     ORDER: 'ORDER',
     OR: 'OR',
 
+    INDEX_HINTS: 'INDEX_HINTS',
+
+    FORCE_INDEX: 'FORCE INDEX',
+    USE_INDEX: 'USE INDEX',
+    IGNORE_INDEX: 'IGNORE INDEX',
+
     PAGE: 'PAGE',
     PAGINATION: 'PAGINATION',
+    POLYGON: 'POLYGON',
+    POINT: 'POINT',
     RIGHT_OUTER: 'RIGHT_OUTER',
 
     SECOND: 'SECOND',

package/src/api/orm/builders/ConditionBuilder.ts

@@ -107,9 +107,18 @@ export abstract class ConditionBuilder<
         [C6C.BETWEEN, C6C.BETWEEN],
         ['BETWEEN', C6C.BETWEEN],
         ['NOT BETWEEN', 'NOT BETWEEN'],
+        [C6C.EXISTS, C6C.EXISTS],
+        ['EXISTS', C6C.EXISTS],
+        ['NOT EXISTS', 'NOT EXISTS'],
         [C6C.MATCH_AGAINST, C6C.MATCH_AGAINST],
     ]);
 
+    private readonly BOOLEAN_FUNCTION_KEYS = new Set<string>([
+        C6C.ST_CONTAINS?.toUpperCase?.() ?? 'ST_CONTAINS',
+        C6C.ST_WITHIN?.toUpperCase?.() ?? 'ST_WITHIN',
+        C6C.MBRCONTAINS?.toUpperCase?.() ?? 'MBRCONTAINS',
+    ]);
+
     private isTableReference(val: any): boolean {
         if (typeof val !== 'string') return false;
         // Support aggregate aliases (e.g., SELECT COUNT(x) AS cnt ... HAVING cnt > 1)
@@ -313,6 +322,10 @@ export abstract class ConditionBuilder<
             return { sql: asParam(operand), isReference: false, isExpression: false, isSubSelect: false };
         }
 
+        if (typeof Buffer !== 'undefined' && Buffer.isBuffer && Buffer.isBuffer(operand)) {
+            return { sql: asParam(operand), isReference: false, isExpression: false, isSubSelect: false };
+        }
+
         if (typeof operand === 'string') {
             if (this.isTableReference(operand) || this.isColumnRef(operand)) {
                 return { sql: operand, isReference: true, isExpression: false, isSubSelect: false };
@@ -365,6 +378,143 @@ export abstract class ConditionBuilder<
         throw new Error('Unsupported operand type in SQL expression.');
     }
 
+    private ensurePlainObject<T>(value: T): any {
+        if (value instanceof Map) {
+            return Object.fromEntries(value as unknown as Map<string, any>);
+        }
+        return value;
+    }
+
+    private resolveExistsInnerColumn(subRequest: Record<string, any>, provided?: string): string {
+        if (provided) {
+            if (typeof provided !== 'string' || provided.trim() === '') {
+                throw new Error('EXISTS correlation column must be a non-empty string.');
+            }
+            return provided;
+        }
+
+        const selectClause = this.ensurePlainObject(subRequest?.[C6C.SELECT]);
+        if (Array.isArray(selectClause) && selectClause.length > 0) {
+            const candidate = selectClause[0];
+            if (typeof candidate === 'string' && candidate.trim() !== '') {
+                return candidate;
+            }
+        }
+
+        const fromTable = subRequest?.[C6C.FROM];
+        if (typeof fromTable === 'string' && fromTable.trim() !== '') {
+            const table = this.config.C6?.TABLES?.[fromTable.trim()];
+            const primary = table?.PRIMARY;
+            if (Array.isArray(primary) && primary.length > 0) {
+                return String(primary[0]);
+            }
+        }
+
+        throw new Error('EXISTS requires a correlation column to be provided or inferable from the subselect.');
+    }
+
+    private normalizeExistsSpec(
+        spec: any
+    ): { outerColumn: string; subRequest: Record<string, any>; innerColumn?: string } {
+        const normalized = this.ensurePlainObject(spec);
+
+        if (!Array.isArray(normalized) || normalized.length < 2) {
+            throw new Error('EXISTS expects an array like [outerColumn, subselect, innerColumn?].');
+        }
+
+        const [outerRaw, payloadRaw, innerRaw] = normalized;
+        if (typeof outerRaw !== 'string' || outerRaw.trim() === '') {
+            throw new Error('EXISTS requires the first element to be an outer column reference string.');
+        }
+
+        const payload = this.ensurePlainObject(payloadRaw);
+        let subSelect: any;
+        if (payload && typeof payload === 'object' && C6C.SUBSELECT in payload) {
+            subSelect = this.ensurePlainObject(payload[C6C.SUBSELECT]);
+        } else if (payload && typeof payload === 'object') {
+            subSelect = payload;
+        } else {
+            throw new Error('EXISTS requires a subselect payload as the second element.');
+        }
+
+        if (!subSelect || typeof subSelect !== 'object') {
+            throw new Error('EXISTS subselect payload must be an object.');
+        }
+
+        const innerColumn = typeof innerRaw === 'string' ? innerRaw : undefined;
+
+        return {
+            outerColumn: outerRaw,
+            subRequest: { ...subSelect },
+            innerColumn,
+        };
+    }
+
+    private buildExistsExpression(
+        spec: any,
+        operator: string,
+        params: any[] | Record<string, any>
+    ): string {
+        const { outerColumn, subRequest, innerColumn } = this.normalizeExistsSpec(spec);
+
+        const fromTableRaw = subRequest[C6C.FROM];
+        if (typeof fromTableRaw !== 'string' || fromTableRaw.trim() === '') {
+            throw new Error('EXISTS subselect requires a table specified with C6C.FROM.');
+        }
+        const fromTable = fromTableRaw.trim();
+
+        this.assertValidIdentifier(outerColumn, 'EXISTS correlation column');
+        const correlationColumn = this.resolveExistsInnerColumn(subRequest, innerColumn);
+        if (!this.isColumnRef(correlationColumn) && !this.isTableReference(correlationColumn)) {
+            throw new Error(`Unknown column reference '${correlationColumn}' used in EXISTS subquery correlation column.`);
+        }
+
+        const existingWhereRaw = this.ensurePlainObject(subRequest[C6C.WHERE]);
+        const correlationCondition = { [correlationColumn]: [C6C.EQUAL, outerColumn] };
+
+        const normalizedExistingWhere = existingWhereRaw && typeof existingWhereRaw === 'object'
+            ? Array.isArray(existingWhereRaw)
+                ? existingWhereRaw.slice()
+                : { ...(existingWhereRaw as Record<string, any>) }
+            : existingWhereRaw;
+
+        const hasExistingWhere = Array.isArray(normalizedExistingWhere)
+            ? normalizedExistingWhere.length > 0
+            : normalizedExistingWhere && typeof normalizedExistingWhere === 'object'
+                ? Object.keys(normalizedExistingWhere).length > 0
+                : normalizedExistingWhere != null;
+
+        let whereClause: any;
+        if (!hasExistingWhere) {
+            whereClause = correlationCondition;
+        } else if (
+            normalizedExistingWhere && typeof normalizedExistingWhere === 'object' &&
+            Object.keys(normalizedExistingWhere).some(key => this.BOOLEAN_OPERATORS.has(key))
+        ) {
+            whereClause = { [C6C.AND]: [normalizedExistingWhere, correlationCondition] };
+        } else if (normalizedExistingWhere && typeof normalizedExistingWhere === 'object') {
+            whereClause = { ...normalizedExistingWhere, ...correlationCondition };
+        } else {
+            whereClause = { [C6C.AND]: [normalizedExistingWhere, correlationCondition] };
+        }
+
+        const subRequestWithCorrelation = {
+            ...subRequest,
+            [C6C.FROM]: fromTable,
+            [C6C.WHERE]: whereClause,
+            [C6C.SELECT]: subRequest[C6C.SELECT] ?? ['1'],
+        };
+
+        const buildScalarSubSelect = (this as any).buildScalarSubSelect;
+        if (typeof buildScalarSubSelect !== 'function') {
+            throw new Error('EXISTS operator requires SelectQueryBuilder context.');
+        }
+
+        const scalar = buildScalarSubSelect.call(this, subRequestWithCorrelation, params);
+        const keyword = operator === 'NOT EXISTS' ? 'NOT EXISTS' : C6C.EXISTS;
+        return `${keyword} ${scalar}`;
+    }
+
     private buildOperatorExpression(
         op: string,
         rawOperands: any,
@@ -373,6 +523,15 @@ export abstract class ConditionBuilder<
     ): string {
         const operator = this.formatOperator(op);
 
+        if (operator === C6C.EXISTS || operator === 'NOT EXISTS') {
+            const operands = Array.isArray(rawOperands) ? rawOperands : [rawOperands];
+            if (!operands.length) {
+                throw new Error(`${operator} requires at least one subselect specification.`);
+            }
+            const clauses = operands.map(spec => this.buildExistsExpression(spec, operator, params));
+            return this.joinBooleanParts(clauses, 'AND');
+        }
+
         if (operator === C6C.MATCH_AGAINST) {
             if (!Array.isArray(rawOperands) || rawOperands.length !== 2) {
                 throw new Error('MATCH_AGAINST requires an array of two operands.');
@@ -497,6 +656,20 @@ export abstract class ConditionBuilder<
             value = Object.fromEntries(value);
         }
 
+        if (typeof column === 'string') {
+            const normalizedColumn = column.trim().toUpperCase();
+            if (this.BOOLEAN_FUNCTION_KEYS.has(normalizedColumn)) {
+                if (!Array.isArray(value)) {
+                    throw new Error(`${column} expects an array of arguments.`);
+                }
+                return this.buildFunctionCall(column, value, params);
+            }
+        }
+
+        if (typeof Buffer !== 'undefined' && Buffer.isBuffer && Buffer.isBuffer(value)) {
+            return this.buildOperatorExpression(C6C.EQUAL, [column, value], params, column);
+        }
+
         if (Array.isArray(value)) {
             if (value.length >= 2 && typeof value[0] === 'string') {
                 const [op, ...rest] = value;

package/src/api/orm/builders/JoinBuilder.ts

@@ -5,12 +5,159 @@ import {resolveDerivedTable, isDerivedTableKey} from "../queryHelpers";
 
 export abstract class JoinBuilder<G extends OrmGenerics> extends ConditionBuilder<G>{
 
+    private indexHintCache?: Map<string, string>;
+
     protected createSelectBuilder(
         _request: any
     ): { build(table: string, isSubSelect: boolean): { sql: string; params: any[] | Record<string, any> } } {
         throw new Error('Subclasses must implement createSelectBuilder to support derived table serialization.');
     }
 
+    protected resetIndexHints(): void {
+        this.indexHintCache = undefined;
+    }
+
+    private normalizeIndexHintKey(key: string): string {
+        return key
+            .replace(/`/g, '')
+            .replace(/_/g, ' ')
+            .trim()
+            .replace(/\s+/g, ' ')
+            .toUpperCase();
+    }
+
+    private normalizeHintTargetKey(target: string): string {
+        return target.replace(/`/g, '').trim();
+    }
+
+    private hasIndexHintKeys(obj: Record<string, any>): boolean {
+        const keys = Object.keys(obj ?? {});
+        if (!keys.length) return false;
+
+        const forceKey = this.normalizeIndexHintKey(C6C.FORCE_INDEX);
+        const useKey = this.normalizeIndexHintKey(C6C.USE_INDEX);
+        const ignoreKey = this.normalizeIndexHintKey(C6C.IGNORE_INDEX);
+
+        return keys.some(key => {
+            const normalized = this.normalizeIndexHintKey(key);
+            return normalized === forceKey || normalized === useKey || normalized === ignoreKey;
+        });
+    }
+
+    private normalizeHintSpec(spec: any): Record<string, any> | undefined {
+        if (spec instanceof Map) {
+            spec = Object.fromEntries(spec);
+        }
+
+        if (Array.isArray(spec) || typeof spec === 'string') {
+            return { [C6C.FORCE_INDEX]: spec } as Record<string, any>;
+        }
+
+        if (!spec || typeof spec !== 'object') {
+            return undefined;
+        }
+
+        if (!this.hasIndexHintKeys(spec as Record<string, any>)) {
+            return undefined;
+        }
+
+        return spec as Record<string, any>;
+    }
+
+    private formatIndexHintClause(spec: any): string {
+        const normalizedSpec = this.normalizeHintSpec(spec);
+        if (!normalizedSpec) return '';
+
+        const clauses: string[] = [];
+        const forceKey = this.normalizeIndexHintKey(C6C.FORCE_INDEX);
+        const useKey = this.normalizeIndexHintKey(C6C.USE_INDEX);
+        const ignoreKey = this.normalizeIndexHintKey(C6C.IGNORE_INDEX);
+
+        const pushClause = (keyword: string, rawValue: any) => {
+            const values = Array.isArray(rawValue) ? rawValue : [rawValue];
+            const indexes = values
+                .map(value => String(value ?? '').trim())
+                .filter(Boolean)
+                .map(value => `\`${value.replace(/`/g, '``')}\``);
+            if (!indexes.length) return;
+            clauses.push(`${keyword} (${indexes.join(', ')})`);
+        };
+
+        for (const [key, rawValue] of Object.entries(normalizedSpec)) {
+            const normalizedKey = this.normalizeIndexHintKey(key);
+            if (normalizedKey === forceKey) {
+                pushClause('FORCE INDEX', rawValue);
+            } else if (normalizedKey === useKey) {
+                pushClause('USE INDEX', rawValue);
+            } else if (normalizedKey === ignoreKey) {
+                pushClause('IGNORE INDEX', rawValue);
+            }
+        }
+
+        return clauses.join(' ');
+    }
+
+    private normalizeIndexHints(raw: any): Map<string, string> | undefined {
+        if (raw instanceof Map) {
+            raw = Object.fromEntries(raw);
+        }
+
+        const cache = new Map<string, string>();
+
+        const addEntry = (target: string, spec: any) => {
+            const clause = this.formatIndexHintClause(spec);
+            if (!clause) return;
+            const normalizedTarget = target === '__base__'
+                ? '__base__'
+                : this.normalizeHintTargetKey(target);
+            cache.set(normalizedTarget, clause);
+        };
+
+        if (Array.isArray(raw) || typeof raw === 'string') {
+            addEntry('__base__', raw);
+        } else if (raw && typeof raw === 'object') {
+            if (this.hasIndexHintKeys(raw as Record<string, any>)) {
+                addEntry('__base__', raw);
+            } else {
+                for (const [key, value] of Object.entries(raw as Record<string, any>)) {
+                    const normalizedKey = this.normalizeHintTargetKey(key);
+                    if (!normalizedKey) continue;
+                    addEntry(normalizedKey, value);
+                }
+            }
+        }
+
+        return cache.size ? cache : undefined;
+    }
+
+    protected getIndexHintClause(table: string, alias?: string): string {
+        if (!this.indexHintCache) {
+            const rawHints = (this.request as unknown as Record<string, any> | undefined)?.[C6C.INDEX_HINTS];
+            this.indexHintCache = this.normalizeIndexHints(rawHints);
+        }
+
+        const hints = this.indexHintCache;
+        if (!hints || hints.size === 0) return '';
+
+        const normalizedTable = this.normalizeHintTargetKey(table);
+        const normalizedAlias = alias ? this.normalizeHintTargetKey(alias) : undefined;
+
+        const candidates = [
+            normalizedAlias,
+            normalizedAlias ? `${normalizedTable} ${normalizedAlias}` : undefined,
+            normalizedTable,
+            '__base__',
+        ];
+
+        for (const candidate of candidates) {
+            if (!candidate) continue;
+            const clause = hints.get(candidate);
+            if (clause) return clause;
+        }
+
+        return '';
+    }
+
     buildJoinClauses(joinArgs: any, params: any[] | Record<string, any>): string {
         let sql = '';
 
@@ -79,7 +226,9 @@ export abstract class JoinBuilder<G extends OrmGenerics> extends ConditionBuilde
                     if (alias) {
                         this.registerAlias(alias, table);
                     }
-                    const joinSql = alias ? `\`${table}\` AS \`${alias}\`` : `\`${table}\``;
+                    const hintClause = this.getIndexHintClause(table, alias);
+                    const baseJoinSql = alias ? `\`${table}\` AS \`${alias}\`` : `\`${table}\``;
+                    const joinSql = hintClause ? `${baseJoinSql} ${hintClause}` : baseJoinSql;
                     const onClause = this.buildBooleanJoinedConditions(conditions, true, params);
                     sql += ` ${joinKind} JOIN ${joinSql}`;
                     if (onClause) {

package/src/api/orm/queries/SelectQueryBuilder.ts

@@ -16,6 +16,7 @@ export class SelectQueryBuilder<G extends OrmGenerics> extends PaginationBuilder
         // reset any previously collected SELECT aliases (from AggregateBuilder)
         // @ts-ignore
         if (this.selectAliases && this.selectAliases.clear) this.selectAliases.clear();
+        this.resetIndexHints();
         const args = this.request;
         this.initAlias(table, args.JOIN);
         const params = this.useNamedParams ? {} : [];
@@ -25,6 +26,10 @@ export class SelectQueryBuilder<G extends OrmGenerics> extends PaginationBuilder
             .join(', ');
 
         let sql = `SELECT ${selectFields} FROM \`${table}\``;
+        const baseIndexHint = this.getIndexHintClause(table);
+        if (baseIndexHint) {
+            sql += ` ${baseIndexHint}`;
+        }
 
         if (args.JOIN) {
             sql += this.buildJoinClauses(args.JOIN, params);