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",
        "relationship": "author_articles",
        "arguments": {}
      },
      "predicate": {
        "type": "binary_comparison_operator",
        "column": {
          "type": "column",
          "name": "title"
        },
        "operator": "like",
        "value": {
          "type": "scalar",
          "value": "Functional"
        }
      }
    }
  },
  "collection_relationships": {
    "author_articles": {
      "arguments": {
        "author_id": {
          "type": "column",
          "name": "id"
        }
      },
      "column_mapping": {},
      "relationship_type": "array",
      "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": "aggregate",
            "aggregate": {
              "type": "star_count"
            },
            "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

CAUTION

Field arguments considered somewhat unstable. Fields arguments are not well supported across all aspects of the specification. It is not recommended that field arguments are used, except for very specialized, advanced use cases.

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.