soql 1.2.0

Models and query generator for Salesforce Object Query Language (SOQL)

This package provides declarative models for Salesforce objects and utilities for generating Salesforce Object Query Language (SOQL) queries from these models.

This package works well with Simple Salesforce.

Usage

from simple_salesforce import Salesforce
from soql import attributes
from soql import load_models_from_salesforce_data
from soql import Model
from soql import select


class Account(Model):
    id = attributes.String('Id')
    deleted = attributes.Boolean('IsDeleted')
    name = attributes.String('Name')
    owner = attributes.Relationship('Owner', related_model=User)
    custom_field = attributes.String('CustomField__c', nullable=True)

class User(Model):
    id = attributes.String('Id')
    email = attributes.String('Email')

sf = Salesforce(...)

query = select(Account) \
    .where(Account.id == '50130000000014c') \
    .join(Account.owner)

resp = sf.query(str(query))

account = load_models_from_salesforce_data(resp)[0]

print(account.id)
print(account.owner.id)

Models

Models define in-memory representations of Salesforce object, and provide an idiomatic way to access the data.

from soql import attributes
from soql import Model

class User(Model):
    # The first argument to an attribute is its name in Salesforce.
    id = attributes.String('Id')
    email = attributes.String('Email')

user = User(id='123', email='[e-mail]')

assert user.id == '123'

Helpers are available to load models directly from simple_salesforce:

query = select(User)

resp = sf.query(str(query))

users = load_models_from_salesforce_data(resp)

Relationships can also be declared:

class Account(Model):
    id = attributes.String('Id')
    owner = attributes.Relationship('Owner', related_model=User)
    contacts = attributes.Relationship('Contacts', related_model=User, many=True, nullable=True)

Queries

SOQL queries can be generated from models:

from soql import select

query = select(User).where(User.id == '123')

assert str(query) == "SELECT User.Id, User.Email FROM User WHERE User.Id = '123'"

Most of SOQL is supported, including…

Joins:

from soql import select

query = select(Account).join(Account.contacts)

assert str(query) == "SELECT Account.Id, (SELECT User.Id, User.Email FROM Account.Contacts) FROM Account"

Subqueries:

from soql import select

subquery = select(User).columns(User.email).subquery()
query = select(User).where(User.email.in_(subquery))

assert str(query) == "SELECT User.Id, User.Email FROM User WHERE User.Email IN (SELECT User.Email FROM User)"

And more!

Installation

pip install soql

Contributing

There is still work to be done, and contributions are encouraged! Check out the contribution guide for more information.