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.