Bulk Reference

Salesforce Bulk API 2.0 Client.

This module provides the SfBulk class, a client for interacting with the Salesforce Bulk API 2.0. It facilitates the creation, management, and execution of bulk jobs for queries and DML operations through logically separated 'query' and 'ingest' handlers.

SfBulk

SfBulk(sf, interval=5, timeout=30)

A client for the Salesforce Bulk API 2.0.

This class provides functionalities to execute queries and DML operations via the Bulk API 2.0. Operations are grouped under the query and ingest attributes for logical separation.

ATTRIBUTE	DESCRIPTION
bulk2_url	The base URL for Bulk API 2.0 endpoints. TYPE: str
headers	The HTTP headers for authentication. TYPE: dict[str, str]
query	Handler for query operations. TYPE: Query
ingest	Handler for ingest (CRUD) operations. TYPE: Ingest
_interval	The default waiting interval in seconds. TYPE: int
_timeout	The request timeout in seconds. TYPE: int

PARAMETER	DESCRIPTION
sf	An authenticated Salesforce client instance. TYPE: Sf
interval	The default interval in seconds for waiting job status. TYPE: int DEFAULT: 5
timeout	The timeout in seconds for API requests. TYPE: int DEFAULT: 30

Query

Query(sf_bulk)

Handle Bulk API 2.0 Query operations.

create

create(query, *, include_all=False)

Create a query job.

PARAMETER	DESCRIPTION
query	The SOQL query to be executed. TYPE: str
include_all	If True, the operation is 'queryAll' to include archived and deleted records. Defaults to False. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
SfBulkJobQuery	An object to manage the created query job.

get_info

get_info(job_id)

Get information about a specific query job.

PARAMETER	DESCRIPTION
job_id	The ID of the query job. TYPE: str

RETURNS	DESCRIPTION
dict[str, Any]	A dictionary containing the job's information.

wait

wait(job_id, interval=None)

Wait a query job's status until it completes.

PARAMETER	DESCRIPTION
job_id	The ID of the query job to wait. TYPE: str
interval	The waiting interval in seconds. If None, the default is used. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
dict[str, Any]	The final job information dictionary after completion.

get_results

get_results(job_id, format_type='dict')

Get the results of a completed query job.

PARAMETER	DESCRIPTION
job_id	The ID of the query job. TYPE: str
format_type	The desired output format. TYPE: FormatType DEFAULT: 'dict'

RETURNS	DESCRIPTION
ResultType	The query results in the specified format.

Ingest

Ingest(sf_bulk)

Handle Bulk API 2.0 Ingest (CRUD) operations.

create_insert

create_insert(object_name)

Create an insert job.

PARAMETER	DESCRIPTION
object_name	The Salesforce object API name (e.g., 'Account'). TYPE: str

RETURNS	DESCRIPTION
SfBulkJob	An object to manage the created insert job.

create_update

create_update(object_name)

Create an update job.

PARAMETER	DESCRIPTION
object_name	The Salesforce object API name (e.g., 'Account'). TYPE: str

RETURNS	DESCRIPTION
SfBulkJob	An object to manage the created update job.

create_upsert

create_upsert(object_name, external_id_field)

Create an upsert job.

PARAMETER	DESCRIPTION
object_name	The Salesforce object API name (e.g., 'Account'). TYPE: str
external_id_field	The API name of the external ID field. TYPE: str

RETURNS	DESCRIPTION
SfBulkJob	An object to manage the created upsert job.

create_delete

create_delete(object_name)

Create a delete job (moves records to the recycle bin).

PARAMETER	DESCRIPTION
object_name	The Salesforce object API name (e.g., 'Account'). TYPE: str

RETURNS	DESCRIPTION
SfBulkJob	An object to manage the created delete job.

create_hard_delete

create_hard_delete(object_name)

Create a hard delete job (permanently deletes records).

PARAMETER	DESCRIPTION
object_name	The Salesforce object API name (e.g., 'Account'). TYPE: str

RETURNS	DESCRIPTION
SfBulkJob	An object to manage the created hard delete job.

upload_data

upload_data(job_id, csv_data)

Upload CSV data to a job.

PARAMETER	DESCRIPTION
job_id	The ID of the ingest job. TYPE: str
csv_data	A string containing the data in CSV format. TYPE: str

complete_upload

complete_upload(job_id)

Signal that data upload is complete for a job.

This moves the job from the 'Open' state to the 'UploadComplete' state, making it ready for processing.

PARAMETER	DESCRIPTION
job_id	The ID of the ingest job. TYPE: str

get_info

get_info(job_id)

Get information about a specific ingest job.

PARAMETER	DESCRIPTION
job_id	The ID of the ingest job. TYPE: str

RETURNS	DESCRIPTION
dict[str, Any]	A dictionary containing the job's information.

wait

wait(job_id, interval=None)

Wait an ingest job's status until it completes.

PARAMETER	DESCRIPTION
job_id	The ID of the ingest job to wait. TYPE: str
interval	The waiting interval in seconds. If None, the default is used. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
dict[str, Any]	The final job information dictionary after completion.

get_successful_results

get_successful_results(job_id, format_type='dict')

Get the successful records from a completed ingest job.

PARAMETER	DESCRIPTION
job_id	The ID of the ingest job. TYPE: str
format_type	The desired output format. Defaults to 'dict'. TYPE: FormatType DEFAULT: 'dict'

RETURNS	DESCRIPTION
ResultType	The query results in the specified format.

get_failed_results

get_failed_results(job_id, format_type='dict')

Get the failed records from a completed ingest job.

PARAMETER	DESCRIPTION
job_id	The ID of the ingest job. TYPE: str
format_type	The desired output format. Defaults to 'dict'. TYPE: FormatType DEFAULT: 'dict'

RETURNS	DESCRIPTION
ResultType	The query results in the specified format.

get_unprocessed_records

get_unprocessed_records(job_id, format_type='dict')

Get unprocessed records from an ingest job.

PARAMETER	DESCRIPTION
job_id	The ID of the ingest job. TYPE: str
format_type	The desired output format. Defaults to 'dict'. TYPE: FormatType DEFAULT: 'dict'

RETURNS	DESCRIPTION
ResultType	The query results in the specified format.

create_job

create_job(object_name, operation, external_id_field=None)

Create a generic ingest job (internal helper).