Field Selection

A Query can specify which fields to fetch. The available fields are either

• the columns on the selected collection (i.e. those advertised in the corresponding CollectionInfo structure in the schema response), or
• fields from related collections

The requested fields are specified as a collection of Field structures in the field property on the Query.

Field Arguments

Arguments can be supplied to fields via the arguments key. These match the format described in the arguments documentation.

The schema response will specify which fields take arguments via its respective arguments key.

If a field has any arguments defined, then the arguments field must be provided wherever that field is referenced. All fields are required, including nullable fields.

Nested Fields

Queries can specify nested field selections for columns which have structured types (that is, not simply a scalar type or a nullable scalar type).

In order to specify nested field selections, the fields property of the Field structure, which is a NestedField structure.

If fields is omitted, the entire structure of the column's data should be returned.

If fields is provided, its value should be compatible with the type of the column:

• For an object-typed column (whether nullable or not), the fields property should contain a NestedField with type object. The fields property of the NestedField specifies a Field structure for each requested nested field from the objects.
• For an array-typed column (whether nullable or not), the fields property should contain a NestedField with type array. The fields property of the NestedField should contain another NestedField structure, compatible with the type of the elements of the array. The selection function denoted by this nested NestedField structure should be applied to each element of each array.

Examples

Simple column selection

Here is an example of a query which selects some columns from the articles collection of the reference data connector:

{
    "collection": "articles",
    "arguments": {},
    "query": {
        "fields": {
            "id": {
                "type": "column",
                "column": "id"
            },
            "title": {
                "type": "column",
                "column": "title"
            }
        }
    },
    "collection_relationships": {}
}

Example with Nested Object Types

Here is an example of a query which selects some columns from a nested object inside the rows of the institutions collection of the reference data connector:

{
    "collection": "institutions",
    "arguments": {},
    "query": {
        "fields": {
            "id": {
                "type": "column",
                "column": "id"
            },
            "location": {
                "type": "column",
                "column": "location",
                "fields": {
                    "type": "object",
                    "fields": {
                        "city": {
                            "type": "column",
                            "column": "city"
                        },
                        "campuses": {
                            "type": "column",
                            "column": "campuses",
                            "arguments": {
                                "limit": {
                                    "type": "literal",
                                    "value": null
                                }
                            }
                        }
                    }
                }
            },
            "location_all": {
                "type": "column",
                "column": "location"
            }
        }
    },
    "collection_relationships": {}
}

Notice that the location column is fetched twice: once to illustrate the use of the fields property, to fetch a subset of data, and again in the location_all field, which omits the fields property and fetches the entire structure.

Example with Nested Array Types

Here is an example of a query which selects some columns from a nested array inside the rows of the institutions collection of the reference data connector:

{
    "collection": "institutions",
    "arguments": {},
    "query": {
        "fields": {
            "id": {
                "type": "column",
                "column": "id"
            },
            "staff": {
                "type": "column",
                "column": "staff",
                "arguments": {
                    "limit": {
                        "type": "literal",
                        "value": null
                    }
                },
                "fields": {
                    "type": "array",
                    "fields": {
                        "type": "object",
                        "fields": {
                            "last_name": {
                                "type": "column",
                                "column": "last_name"
                            },
                            "fields_of_study": {
                                "type": "column",
                                "column": "specialities",
                                "arguments": {
                                    "limit": {
                                        "type": "literal",
                                        "value": null
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "departments": {
                "type": "column",
                "column": "departments",
                "arguments": {
                    "limit": {
                        "type": "literal",
                        "value": null
                    }
                }
            }
        }
    },
    "collection_relationships": {}
}

Notice that the staff column is fetched using a fields property of type array. For each staff member in each institution row, we apply the selection function denoted by its fields property (of type object). Specifically, the last_name and specialities properties are selected for each staff member.

Example with Field Arguments

Here is an example of a query which selects some columns from a nested array inside the rows of the institutions collection of the reference data connector and uses the limit field argument to limit the number of items returned:

{
    "$schema": "../../../../ndc-models/tests/json_schema/query_request.jsonschema",
    "collection": "institutions",
    "arguments": {},
    "query": {
        "fields": {
            "id": {
                "type": "column",
                "column": "id"
            },
            "staff": {
                "type": "column",
                "column": "staff",
                "arguments": {
                    "limit": {
                        "type": "literal",
                        "value": 1
                    }
                },
                "fields": {
                    "type": "array",
                    "fields": {
                        "type": "object",
                        "fields": {
                            "last_name": {
                                "type": "column",
                                "column": "last_name"
                            },
                            "fields_of_study": {
                                "type": "column",
                                "column": "specialities",
                                "arguments": {
                                    "limit": {
                                        "type": "literal",
                                        "value": 2
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "departments": {
                "type":"column",
                "column": "departments",
                "arguments": {
                    "limit": {
                        "type": "literal",
                        "value": null
                    }
                }
            }
        }
    },
    "collection_relationships": {}
}

Requirements

• If the QueryRequest contains a Query which specifies fields, then each RowSet in the response should contain the rows property, and each row should contain all of the requested fields.

See also

• Type Query
• Type RowFieldValue
• Type RowSet