Querying Data#

This guide covers data retrieval with the salespyforce.Salesforce client using:

  • soql_query() for structured record queries (SOQL)

  • search_string() for text search (SOSL FIND { ... })

Before querying, make sure your client is authenticated. See Authentication for setup details.

SOQL Queries With soql_query()#

Use soql_query() when you know which object and fields you want to query.

from salespyforce import Salesforce

sfdc = Salesforce(helper="/path/to/helper.yml")

query = """
SELECT Id, Name, Industry, LastModifiedDate
FROM Account
WHERE IsDeleted = false
ORDER BY LastModifiedDate DESC
LIMIT 10
"""

result = sfdc.soql_query(query)

print(f"Done: {result.get('done')}")
print(f"Total size: {result.get('totalSize')}")
for row in result.get("records", []):
    print(row["Id"], row.get("Name"), row.get("Industry"))

Typical SOQL response keys include:

  • totalSize: Number of records matched by the query.

  • done: True when all available rows for this request are included.

  • records: A list of records.

  • nextRecordsUrl: Present when additional rows are available.

See also

SOQL Pagination (nextRecordsUrl)#

For larger result sets, Salesforce may return a partial page with nextRecordsUrl. Pass that URL back to soql_query() with next_records_url=True.

query = """
SELECT Id, Name
FROM Contact
ORDER BY CreatedDate DESC
"""

response = sfdc.soql_query(query)
all_records = response.get("records", [])

while not response.get("done"):
    response = sfdc.soql_query(
        query=response["nextRecordsUrl"],
        next_records_url=True,
    )
    all_records.extend(response.get("records", []))

print(f"Collected {len(all_records)} contacts")

SOQL Quote Handling (replace_quotes)#

By default, soql_query() replaces double quotes (") with single quotes (') before sending the query (replace_quotes=True).

In most cases, this is convenient. If your query text must preserve double quotes exactly, disable this behavior:

query = 'SELECT Id FROM Account WHERE Name = "Acme"'
result = sfdc.soql_query(query, replace_quotes=False)

Note

Prefer standard SOQL string literals (single quotes) unless you have a specific reason to preserve double quotes in the outgoing query string.

SOSL Searches With search_string()#

Use search_string() for keyword-style search across supported objects.

from salespyforce import Salesforce

sfdc = Salesforce(helper="/path/to/helper.yml")
result = sfdc.search_string("Acme")

for record in result.get("searchRecords", []):
    print(record.get("attributes", {}).get("type"), record.get("Id"), record.get("Name"))

search_string() constructs a SOSL query in the form:

  • FIND {<your search string>}

Use this method when you want quick full-text style search behavior without writing SOSL manually.

Choosing SOQL vs SOSL#

  • Use soql_query() when you need precise filtering, selected fields, sorting, and predictable object-specific queries.

  • Use search_string() when you need text search for records matching a term across searchable fields/objects.

Troubleshooting Query Results#

  • If you receive authentication errors, confirm your client setup in Authentication.

  • If queries fail at runtime, review exception guidance in Error Handling.

  • If expected rows are missing, verify object/field permissions for the API user.

Next Steps#