Arguments
Collection arguments parameterize an entire collection, and must be provided in queries wherever the collection is referenced, either directly, or via relationships.
Field arguments parameterize a single field, and must be provided wherever that field is referenced.
Collection Arguments
Collection arguments should be provided in the QueryRequest
anywhere a collection is referenced. The set of provided arguments should be compatible with the list of arguments required by the corresponding collection in the schema response.
Specifying arguments to the top-level collection
Collection arguments should be provided as key-value pairs in the arguments
property of the top-level QueryRequest
object:
{
"collection": "articles_by_author",
"arguments": {
"author_id": {
"type": "literal",
"value": 1
}
},
"query": {
"fields": {
"id": {
"type": "column",
"column": "id"
},
"title": {
"type": "column",
"column": "title"
}
}
},
"collection_relationships": {}
}
Relationships
Relationships can specify values for arguments on their target collection:
{
"collection": "authors",
"arguments": {},
"query": {
"fields": {
"first_name": {
"type": "column",
"column": "first_name"
},
"last_name": {
"type": "column",
"column": "last_name"
},
"articles": {
"type": "relationship",
"arguments": {},
"relationship": "author_articles",
"query": {
"fields": {
"id": {
"type": "column",
"column": "id"
},
"title": {
"type": "column",
"column": "title"
}
}
}
}
}
},
"collection_relationships": {
"author_articles": {
"arguments": {
"author_id": {
"type": "column",
"name": "id"
}
},
"column_mapping": {
},
"relationship_type": "array",
"source_collection_or_type": "author",
"target_collection": "articles_by_author"
}
}
}
Any arguments which are not defined by the relationship itself should be specified where the relationship is used. For example, here the author_id
argument can be moved from the relationship definition to the field which uses it:
{
"collection": "authors",
"arguments": {},
"query": {
"fields": {
"first_name": {
"type": "column",
"column": "first_name"
},
"last_name": {
"type": "column",
"column": "last_name"
},
"articles": {
"type": "relationship",
"arguments": {
"author_id": {
"type": "column",
"name": "id"
}
},
"relationship": "author_articles",
"query": {
"fields": {
"id": {
"type": "column",
"column": "id"
},
"title": {
"type": "column",
"column": "title"
}
}
}
}
}
},
"collection_relationships": {
"author_articles": {
"arguments": {},
"column_mapping": {},
"relationship_type": "array",
"source_collection_or_type": "author",
"target_collection": "articles_by_author"
}
}
}
Collection arguments in predicates
Arguments must be specified in predicates whenever a reference to a secondary collection is required.
For example, in an EXISTS
expression, if the target collection has arguments:
{
"collection": "authors",
"arguments": {},
"query": {
"fields": {
"id": {
"type": "column",
"column": "id"
}
},
"predicate": {
"type": "exists",
"in_collection": {
"type": "related",
"arguments": {
"author_id": {
"type": "column",
"name": "id"
}
},
"relationship": "author_articles"
},
"predicate": {
"type": "binary_comparison_operator",
"column": {
"type": "column",
"name": "title",
"path": []
},
"operator": "like",
"value": {
"type": "scalar",
"value": "Functional"
}
}
}
},
"collection_relationships": {
"author_articles": {
"arguments": {},
"column_mapping": {},
"relationship_type": "array",
"source_collection_or_type": "author",
"target_collection": "articles_by_author"
}
}
}
Or when a predicate expression matches a column from a related collection:
{
"collection": "authors",
"arguments": {},
"query": {
"fields": {
"id": {
"type": "column",
"column": "id"
}
},
"predicate": {
"type": "binary_comparison_operator",
"column": {
"type": "column",
"name": "title",
"path": [
{
"arguments": {
"author_id": {
"type": "column",
"name": "id"
}
},
"relationship": "author_articles",
"predicate": {
"type": "and",
"expressions": []
}
}
]
},
"operator": "like",
"value": {
"type": "scalar",
"value": "Functional"
}
}
},
"collection_relationships": {
"author_articles": {
"arguments": {},
"column_mapping": {},
"relationship_type": "array",
"source_collection_or_type": "author",
"target_collection": "articles_by_author"
}
}
}
Collection arguments in order_by
Arguments must be specified when an OrderByElement
references a related collection.
For example, when ordering by an aggregate of rows in a related collection, and that collection has arguments:
{
"collection": "authors",
"arguments": {},
"query": {
"fields": {
"id": {
"type": "column",
"column": "id"
}
},
"order_by": {
"elements": [
{
"order_direction": "desc",
"target": {
"type": "star_count_aggregate",
"path": [
{
"arguments": {
"author_id": {
"type": "column",
"name": "id"
}
},
"relationship": "author_articles",
"predicate": {
"type": "and",
"expressions": []
}
}
]
}
}
]
}
},
"collection_relationships": {
"author_articles": {
"arguments": {},
"column_mapping": {},
"relationship_type": "array",
"source_collection_or_type": "author",
"target_collection": "articles_by_author"
}
}
}
Field Arguments
Field arguments can be provided to any field requested (in addition to those described for top-level collections). These are specified in the schema response and their use is described in field selection. Their specification and usage matches that of collection arguments above.