Query

Overview

The Query class provides a fluent, chainable API for building and executing SOQL queries. It supports query construction, execution, streaming, bulk operations, and automatic record fetching.

Creating Queries

From Connection

Create a query directly from a connection object.

const query = conn.query('SELECT Id, Name FROM Account WHERE Industry = \'Technology\'');

From SObject

Use SObject methods to create queries with type safety.

const query = conn.sobject('Account').find({ Industry: 'Technology' });

Query Building Methods

Query building methods are chainable and allow you to construct complex queries programmatically.

select()

Select fields to include in the result.

const query = conn.sobject('Account')
  .select('Id, Name, Industry');

fields

string | string[] | object

Fields to select. Can be:

Comma-separated string
Array of field names
Object with field projection config
’*’ for all fields

where()

Filter records by conditions.

const query = conn.sobject('Account')
  .select('Id, Name')
  .where({ Industry: 'Technology' });

conditions

QueryCondition | string

required

Query conditions object or SOQL WHERE clause string

Show Available operators

$eq - Equals (default if no operator specified)
$ne - Not equals
$gt - Greater than
$gte - Greater than or equal to
$lt - Less than
$lte - Less than or equal to
$like - LIKE pattern matching
$nlike - NOT LIKE pattern matching
$in - IN (value is in list)
$nin - NOT IN
$includes - INCLUDES (for multi-select picklists)
$excludes - EXCLUDES (for multi-select picklists)
$exists - Field has a value (true) or is null (false)
$or - Logical OR
$and - Logical AND

limit()

Limit the number of records returned.

const query = conn.sobject('Account')
  .select('Id, Name')
  .limit(10);

limit

number

required

Maximum number of records to return

skip() / offset()

Skip a specified number of records.

const query = conn.sobject('Account')
  .select('Id, Name')
  .limit(10)
  .skip(20); // Skip first 20 records

offset

number

required

Number of records to skip

sort() / orderby()

Sort query results.

const query = conn.sobject('Account')
  .select('Id, Name')
  .sort({ Name: 'ASC', CreatedDate: 'DESC' });

sort

object | string | array

required

Sort configuration:

Object: { fieldName: 'ASC' | 'DESC' }
String + direction: sort('Name', 'ASC')
Array: [['Name', 'ASC'], ['CreatedDate', 'DESC']]

include()

Include child relationship records in the query.

const query = conn.sobject('Account')
  .select('Id, Name')
  .include('Contacts');

const accounts = await query;
accounts.forEach(account => {
  console.log(account.Contacts.records);
});

childRelName

string

required

Child relationship name (e.g., ‘Contacts’, ‘Opportunities’)

conditions

QueryCondition

Filter conditions for child records

fields

string | string[]

Fields to select from child records

options

object

Show properties

limit

number

Limit child records

offset

number

Skip child records

sort

object

Sort child records

result

SubQuery

Returns a SubQuery instance that can be chained or ended with .end()

Query Execution

execute() / exec() / run()

Execute the query and fetch results.

const query = conn.sobject('Account')
  .select('Id, Name')
  .where({ Industry: 'Technology' })
  .limit(100);

const records = await query.execute();
records.forEach(record => console.log(record.Name));

options

QueryOptions

Show properties

autoFetch

boolean

Automatically fetch all records across multiple queries (default: false)

maxFetch

number

Maximum number of records to fetch (default: 10000)

scanAll

boolean

Include deleted and archived records (default: false)

headers

object

Custom HTTP headers

Promise Interface

Queries implement the Promise interface and auto-execute when awaited.

// Auto-executes when awaited
const records = await conn.sobject('Account')
  .select('Id, Name')
  .where({ Industry: 'Technology' });

// Or use .then()
conn.sobject('Account')
  .select('Id, Name')
  .where({ Industry: 'Technology' })
  .then(records => {
    console.log(records);
  })
  .catch(err => {
    console.error(err);
  });

Query Options

autoFetch()

Enable automatic fetching of all records.

const query = conn.sobject('Account')
  .select('Id, Name')
  .autoFetch(true) // Fetch all records across multiple API calls
  .maxFetch(50000); // Up to 50,000 records

const allRecords = await query;
console.log(`Fetched ${allRecords.length} records`);

autoFetch

boolean

required

Enable (true) or disable (false) automatic fetching

maxFetch()

Set maximum number of records to fetch.

const query = conn.sobject('Account')
  .select('Id, Name')
  .maxFetch(5000); // Fetch up to 5000 records

maxFetch

number

required

Maximum number of records to fetch

scanAll()

Include deleted and archived records.

const query = conn.sobject('Account')
  .select('Id, Name, IsDeleted')
  .scanAll(true); // Uses queryAll instead of query

const allRecords = await query; // Includes deleted records

scanAll

boolean

required

Enable (true) or disable (false) scanning all records

Streaming

stream()

Get a readable stream of query results.

const stream = conn.sobject('Account')
  .select('Id, Name')
  .where({ Industry: 'Technology' })
  .stream('record');

stream.on('data', record => {
  console.log(record.Name);
});

stream.on('end', () => {
  console.log('Done');
});

stream.on('error', err => {
  console.error(err);
});

type

'record' | 'csv'

Stream type (default: ‘csv’)

‘record’: Stream individual record objects
‘csv’: Stream CSV formatted data

result

Readable

Node.js Readable stream

pipe()

Pipe query results to a writable stream.

conn.sobject('Account')
  .select('Id, Name')
  .pipe(process.stdout);

Query Information

toSOQL()

Generate SOQL string from the query.

const query = conn.sobject('Account')
  .select('Id, Name')
  .where({ Industry: 'Technology' })
  .limit(10);

const soql = await query.toSOQL();
console.log(soql);
// "SELECT Id, Name FROM Account WHERE Industry = 'Technology' LIMIT 10"

result

string

SOQL query string

explain()

Get query execution plan.

const query = conn.sobject('Account')
  .select('Id, Name')
  .where({ Industry: 'Technology' });

const plan = await query.explain();

plan.plans.forEach(plan => {
  console.log('Leading operation:', plan.leadingOperationType);
  console.log('Cardinality:', plan.cardinality);
  console.log('Relative cost:', plan.relativeCost);
  console.log('Fields:', plan.fields);
});

result

QueryExplainResult

Show properties

plans

array

Array of execution plan objects

Show plan properties

leadingOperationType

string

Type: ‘Index’, ‘TableScan’, ‘Sharing’, or ‘Other’

cardinality

number

Estimated number of records

relativeCost

number

Relative cost of the operation

sobjectType

string

SObject type

fields

string[]

Fields used in the plan

Bulk Operations

destroy() / delete() / del()

Bulk delete queried records.

const results = await conn.sobject('Account')
  .find({ Industry: 'Test' })
  .destroy();

results.forEach(result => {
  console.log(result.id, result.success);
});

options

QueryDestroyOptions

Show properties

allowBulk

boolean

Allow using Bulk API (default: true)

bulkThreshold

number

Number of records to trigger Bulk API (default: 200)

bulkApiVersion

1 | 2

Bulk API version to use (default: 1)

result

SaveResult[]

Array of save results for deleted records

update()

Bulk update queried records.

const results = await conn.sobject('Account')
  .find({ Industry: 'Technology' })
  .update(record => ({
    ...record,
    Description: `${record.Name} - Technology Account`
  }));

mapping

function | object

required

Either:

Function that takes a record and returns updated fields
Object with fields to update on all records

options

QueryUpdateOptions

Show properties

allowBulk

boolean

Allow using Bulk API (default: true)

bulkThreshold

number

Number of records to trigger Bulk API (default: 200)

bulkApiVersion

1 | 2

Bulk API version to use (default: 1)

skipRecordTemplateEval

boolean

Skip template evaluation for update object

result

SaveResult[]

Array of save results for updated records

Query Events

Queries emit events during execution.

const query = conn.sobject('Account')
  .select('Id, Name')
  .where({ Industry: 'Technology' });

query.on('record', (record, index) => {
  console.log(`Record ${index}:`, record.Name);
});

query.on('end', () => {
  console.log('Query completed');
});

query.on('error', err => {
  console.error('Query error:', err);
});

query.on('fetch', () => {
  console.log('Fetched batch of records');
});

query.execute();

Events

record

event

Emitted for each record fetchedCallback parameters:

record - The record object
index - Record index (0-based)
query - Query instance

end

event

Emitted when query completes

error

event

Emitted on query errorCallback parameters:

error - Error object

fetch

event

Emitted when a batch of records is fetched

response

event

Emitted with final query responseCallback parameters:

response - Query result (type depends on response target)
query - Query instance

Query Properties

totalSize

Total number of records matching the query.

const query = conn.sobject('Account')
  .select('Id')
  .where({ Industry: 'Technology' });

await query.execute();
console.log(`Total records: ${query.totalSize}`);

totalFetched

Number of records fetched so far.

const query = conn.sobject('Account')
  .select('Id')
  .maxFetch(1000);

await query.execute();
console.log(`Fetched: ${query.totalFetched}`);

records

Array of fetched records.

const query = conn.sobject('Account')
  .select('Id, Name')
  .limit(10);

await query.execute();
query.records.forEach(record => console.log(record.Name));

REST API

Authentication

Bulk API

Specialized APIs

Overview

Creating Queries

From Connection

From SObject

Query Building Methods

select()

where()

limit()

skip() / offset()

sort() / orderby()

include()

Query Execution

execute() / exec() / run()

Promise Interface

Query Options

autoFetch()

maxFetch()

scanAll()

Streaming

stream()

pipe()

Query Information

toSOQL()

explain()

Bulk Operations

destroy() / delete() / del()

update()

Query Events

Events

Query Properties

totalSize

totalFetched

records

Build docs developers (and LLMs) love

REST API

Authentication

Bulk API

Specialized APIs

​Overview

​Creating Queries

​From Connection

​From SObject

​Query Building Methods

​select()

​where()

​limit()

​skip() / offset()

​sort() / orderby()

​include()

​Query Execution

​execute() / exec() / run()

​Promise Interface

​Query Options

​autoFetch()

​maxFetch()

​scanAll()

​Streaming

​stream()

​pipe()

​Query Information

​toSOQL()

​explain()

​Bulk Operations

​destroy() / delete() / del()

​update()

​Query Events

​Events

​Query Properties

​totalSize

​totalFetched

​records

Build docs developers (and LLMs) love

Overview

Creating Queries

From Connection

From SObject

Query Building Methods

select()

where()

limit()

skip() / offset()

sort() / orderby()

include()

Query Execution

execute() / exec() / run()

Promise Interface

Query Options

autoFetch()

maxFetch()

scanAll()

Streaming

stream()

pipe()

Query Information

toSOQL()

explain()

Bulk Operations

destroy() / delete() / del()

update()

Query Events

Events

Query Properties

totalSize

totalFetched

records