fields Clause: Selecting Fields to Return

Description

Specifies the fields to be returned in the response to a GET operation on an entity collection.

Applies To

GET method called on entity collections.

Does not apply to GET operations on individual entities. For example, the fields clause in this query has no effect:

../tests/135?fields=contains-test-folder.name

Field names

Fields are identified by logical name. To get the list of fields for an entity, use the XML returned by a GET on the customization fields Collection.

This is an example of a Field element:

<FieldPhysicalName="TS_ATTACHMENT"Name="attachment"Label="Attachment"">

Attribute	Description
PhysicalName	The column name in the project database.
Label	The display string that can be customized.
Name	The logical name.

Use the logical name value to specify fields in:

• group specifications
• order specifications
• Input XMLs to create or update an entity

To limit the results to the fields that can be used in a filter, specify fields?can-filter=true.

To specify fields in another entity, use the unique alias that represents the relation of the second entity to the entity your are querying. See Aliases. For instance:
.../tests?fields=id,contains-test-folder.id,contains-test-folder.name 

Remarks

If the fields clause is not used, all fields are returned.

Limiting the returned fields to those required by your application may significantly improve performance.

Multiple fields are separated with a comma.

Use logical names to identify the fields. See Field Names.

Do not use more than one alias to reference the same entity. For example, in the query ../tests?fields=contains-test-folder.name,test-folder.id, alias contains-test-folder and alias test-folder both refer to test folders. The result of this query will not be what you intended. For more information about aliases, see Relations.

Examples

All fields from one entity type:
    tests?fields=id,name

Using aliases to select from multiple entity types:
    tests?fields=id,test-folder.id,test-folder.name
     For more about queries that reference multiple entity types, see Relations.