Fields Parameter (Spider)

[Table of Contents](https://github.com/dell-oss/Doradus/wiki/Spider Databases: Table-of-Contents) | Previous | Next
Spider Object Queries: Field Parameter

---

When the fields parameter is omitted, all scalar fields of selected objects are returned. When it is provided, there are many options for selecting fields to be returned. These are described below.

Basic Formats

The fields parameter has the following general formats:

• *: Using the value "*" (without quotes) is a synonym for omitting the fields parameter. All scalar fields are returned for each object.

• _all: This keyword requests all scalar fields of each perspective object and the scalar fields of each first-level object connected via a link value.

• _local: This keyword requests all scalar field values and the _ID value of all link fields for each object.

• <scalar field>: When a scalar field is requested, its value (SV) or values (MV), if any, are returned.

• <link field>: When a link field is requested, the _ID of each linked object is returned.

• <group field>: When a group field is requested, all leaf scalar and link fields within the group and its nested groups, recursively, are returned.

• f1,f2,f3: The fields parameter can be a comma-separated list of field names. This example is a simple list of names: only fields f1, f2, and f3 are returned. Each field can be a scalar, link, or group field.

• f1,f2.f3,f2.f4.f5: This example uses dotted notation to define link paths. This example requests three fields: f1, which belongs to the perspective object; f3, which is connected to the perspective object via link f2; and f5, which is related via links f2 to f4. When dotted notation is used, each field to the left of a dot must be a link belonging to the object on its left.

• f=f1,f2(f3,f4(f5)): This is the same example as above using parenthetical qualification instead of dotted notation. Parenthetical and dotted notations can be mixed within a single fields parameter list. Example: f=Name,Manager(Name,Manager.Name).

• f1[s1],f2[s2].f3[s3],f2.f4[s4].f5: This is a dotted notation example where size limits are placed on specific link fields. If f1 is a link field, the number of f1 values returned for each object will be no more than s1, which must be a number. Similarly, link f2 is limited to s2 values per object; f3 is limited to s3 values for each f2 value; and f4 is limited to s4 values per f2 value. Since it has no bracketed parameter, field f5 is not limited in the number of values returned. Link size limits are explained further later.

• f=f1[s1],f2[s2](f3[s3],f4[s4](f5)): This is the same *size limits *example as above using parenthetical qualification instead of dotted notation. Link size limits are explained further later.

WHERE Filters

When link paths are used in the fields parameter, values can be filtered using a WHERE expression. For example, consider this URI query:

.../_query?q=Size>1000&f=InternalRecipients.WHERE(Person.Department:support)

This returns only InternalRecipients whose Person.Department contains the term "support".

The WHERE clause does not have to be applied to the terminal field in the link path. For example:

.../_query?q=Size>1000&f=InternalRecipients.Person.WHERE(Department:support).Office

This returns InternalRecipients.Person.Office values for each message but only for InternalRecipients.Person objects whose Department contains the term "support".

Size Limits on Link Fields

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.