Field Selection

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

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

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"
                        }
                    }
                }
            },
            "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",
                "fields": {
                    "type": "array",
                    "fields": {
                        "type": "object",
                        "fields": {
                            "last_name": {
                                "type": "column",
                                "column": "last_name"
                            },
                            "fields_of_study": {
                                "type": "column",
                                "column": "specialities"
                            }
                        }
                    }
                }
            },
            "departments": {
                "type":"column",
                "column": "departments"
            }
        }
    },
    "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.

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