API Documentation

This part of the documentation covers all the public classes and functions in SQLAlchemy-JSON-API.

class sqlalchemy_json_api.QueryBuilder(model_mapping, base_url=None, type_formatters=None, sort_included=True)[source]

1. Simple example

query_builder = QueryBuilder({
    'articles': Article,
    'users': User,
    'comments': Comment
})
  1. Example using type formatters:

    def isoformat(date):
        return sa.func.to_char(
            date,
            sa.text(''YYYY-MM-DD"T"HH24:MI:SS.US"Z"'')
        ).label(date.name)
    
    query_builder = QueryBuilder(
        {
            'articles': Article,
            'users': User,
            'comments': Comment
        },
        type_formatters={sa.DateTime: isoformat}
    )
    
Parameters:
  • model_mapping

    A mapping with keys representing JSON API resource identifier type names and values as SQLAlchemy models.

    It is recommended to use lowercased pluralized and hyphenized names for resource identifier types. So for example model such as LeagueInvitiation should have an equivalent key of ‘league-invitations’.

  • base_url – Base url to be used for building JSON API compatible links objects. By default this is None indicating that no link objects will be built.
  • type_formatters – A dictionary of type formatters
  • sort_included – Whether or not to sort included objects by type and id.
select(model, **kwargs)[source]

Builds a query for selecting multiple resource instances:

query = query_builder.select(
    Article,
    fields={'articles': ['name', 'author', 'comments']},
    include=['author', 'comments.author'],
    from_obj=session.query(Article).filter(
        Article.id.in_([1, 2, 3, 4])
    )
)

Results can be sorted:

# Sort by id in descending order
query = query_builder.select(
    Article,
    sort=['-id']
)

# Sort by name and id in ascending order
query = query_builder.select(
    Article,
    sort=['name', 'id']
)
Parameters:
  • model – The root model to build the select query from.
  • fields – A mapping of fields. Keys representing model keys and values as lists of model descriptor names.
  • include – List of dot-separated relationship paths.
  • sort – List of attributes to apply as an order by for the root model.
  • limit – Applies an SQL LIMIT to the generated query.
  • offset – Applies an SQL OFFSET to the generated query.
  • links – A dictionary of links to apply as top level links in the built query. Keys representing json keys and values as valid urls or dictionaries.
  • from_obj – A SQLAlchemy selectable (for example a Query object) to select the query results from.
  • as_text – Whether or not to build a query that returns the results as text (raw json).
select_one(model, id, **kwargs)[source]

Builds a query for selecting single resource instance.

query = query_builder.select_one(
    Article,
    1,
    fields={'articles': ['name', 'author', 'comments']},
    include=['author', 'comments.author'],
)
Parameters:
  • model – The root model to build the select query from.
  • id – The id of the resource to select.
  • fields – A mapping of fields. Keys representing model keys and values as lists of model descriptor names.
  • include – List of dot-separated relationship paths.
  • links – A dictionary of links to apply as top level links in the built query. Keys representing json keys and values as valid urls or dictionaries.
  • from_obj – A SQLAlchemy selectable (for example a Query object) to select the query results from.
  • as_text – Whether or not to build a query that returns the results as text (raw json).

Builds a query for selecting related resource(s). This method can be used for building select queries for JSON requests such as:

GET articles/1/author

Usage:

article = session.query(Article).get(1)

query = query_builder.select_related(
    article,
    'category'
)
Parameters:
  • obj – The root object to select the related resources from.
  • fields – A mapping of fields. Keys representing model keys and values as lists of model descriptor names.
  • include – List of dot-separated relationship paths.
  • links – A dictionary of links to apply as top level links in the built query. Keys representing json keys and values as valid urls or dictionaries.
  • sort – List of attributes to apply as an order by for the root model.
  • from_obj – A SQLAlchemy selectable (for example a Query object) to select the query results from.
  • as_text – Whether or not to build a query that returns the results as text (raw json).
select_relationship(obj, relationship_key, **kwargs)[source]

Builds a query for selecting relationship resource(s):

article = session.query(Article).get(1)

query = query_builder.select_related(
    article,
    'category'
)
Parameters:
  • obj – The root object to select the related resources from.
  • sort – List of attributes to apply as an order by for the root model.
  • links – A dictionary of links to apply as top level links in the built query. Keys representing json keys and values as valid urls or dictionaries.
  • from_obj – A SQLAlchemy selectable (for example a Query object) to select the query results from.
  • as_text – Whether or not to build a query that returns the results as text (raw json).
exception sqlalchemy_json_api.IdPropertyNotFound[source]
exception sqlalchemy_json_api.InvalidField[source]
exception sqlalchemy_json_api.UnknownField[source]
exception sqlalchemy_json_api.UnknownModel[source]
exception sqlalchemy_json_api.UnknownFieldKey[source]