Link Field Size Limits

When the fields parameter includes link fields, the maximum number of values returned for each link can be controlled individually. As an example, consider the following link path:

A -> B -> (C, D)

That is, A is a link from the perspective object, B is a link from A’s extent, and B’s extent has two link fields C and D. If the query includes a query-level page size parameter, it controls the maximum number of objects returned, but not the number of link field values returned. For example, the following queries are all identical, showing different forms of dotted and parenthetical qualification currently allowed for the f parameter:

.../_query?f=A(B(C,D)))&s=10&q=...

.../_query?f=A.B(C,D)&s=10&q=...

.../_query?f=A.B.C,A.B.D&s=10&q=...

In these queries, the maximum number of objects returned is 10, but the number of A, B, C, or D values returned for any object is unlimited.

To limit the maximum number of values returned for a link field, a size limit can be given in square brackets immediately after the link field name. Suppose we want to limit the number of A values returned to 5. This can be done with either of the following queries:

.../_query?f=A[5](B(C,D)))&s=10&q=...

.../_query?f=A[5].B(C,D))&s=10&q=...

In these queries, the maximum objects returned is 10, the number of values returned for B, C, and D is unlimited, and the maximum number of A values returned for each object is 5.

To control the maximum values of both A and B, either of the following syntaxes can be used:

.../_query?f=A[5](B[4](C,D))&s=10&q=... // alternative #1

.../_query?f=A[5].B[4](C,D)&s=10&q=... // alternative #2

These two syntax variations are identical, limiting A to 5 values for each perspective object and B to 4 values for each A value. The maximum object limits is still 10, and the field value limits for C and D is unlimited.

To limit the number of values for C and D (but not A or B), we can use any of the following syntax variations:

.../_query?f=A(B(C[4],D[3]))&s=10&q=... // alternative #1

.../_query?f=A.B(C[4],D[3])&s=10&q=... // alternative #2

.../_query?f=A.B.C[4],A.B.D[3]&s=10&q=... // alternative #3

When a WHERE filter is used (see previous section), a size limit for the same field should be provided after the WHERE clause. The following examples show the same query with alternate syntax variations:

.../_query?f=A.WHERE(foo=bar)[5](B.WHERE(foogle=true)(C[4],D[3]))&s=10&q=...

.../_query?f=A.WHERE(foo=bar)[5].B.WHERE(foogle=true)(C[4],D[3])&s=10&q=...

In this example, link A is filtered and limited to 5 values maximum; B is filtered but has no value limit; C is not filtered but limited to 4 values; and D is also not filtered but limited to 3 values.

The WHERE clause is always qualified with a dot, whereas field names can be qualified with a dot or within parentheses. Placing the size limit after the WHERE clause helps to signify that field values are first filtered by the WHERE condition; the filtered set is then limited by the size limit. Also as shown, parenthetical qualification is preferable when multiple extended fields are listed after a link that uses a WHERE filter. (Using purely dotted notation, the WHERE condition would have to be repeated.)

Keeping with current conventions, an explicit size value of zero means “unlimited”. So, for example:

.../_query?f=A[5](B(C,D[3])))&s=0&q=...

This query places no limits on the number of objects returned as well as the number of B values returned for each A, or the number of C values returned for each B. But a maximum of 5 A values are returned for each object, and a maximum of 3 D values are returned for each B.

Note that size limits only apply to link fields: when an MV scalar field is requested, all values are returned.