Function firstByLookupKey

firstByLookupKey<T = Record<string, unknown>>(
    lookupKey: string,
    sql: string,
    bindings?: any[],
    batchSize?: number,
    options?: ReadOptions,
): Promise<T | null>
Retrieves the first record using a secondary lookup key when available.

This helper avoids creating new primary-key mappings for secondary identifiers. It first checks KV for a lookup-key mapping and queries that shard directly. If no mapping exists (or the mapping is stale), it falls back to fanout (firstAllShards) and returns the first non-null result.
Type Parameters
- T = Record<string, unknown>
  Type of the result record
Parameters
- lookupKey: string
  Secondary key such as email:user@example.com or username:alice
- sql: string
  SQL statement to execute
- bindings: any[] = []
  Parameter values to bind to the SQL statement
- batchSize: number = 50
  Number of concurrent shard queries during fanout (default: 50)
- Optionaloptions: ReadOptions
  Read guarantee for this call. The mapped shard and the fanout share one session per shard
Returns Promise<T | null>
Promise resolving to the first matching record, or null

Since
1.1.4
- Defined in src/router.ts:3004