The primary use of the .include element is to specify output fields to display in the result set.
This notion is applied in a similar way in regard to properties. Each item may be annotated with several (even many) properties. In many cases, you may only be interested in a specific subset of the properties, and only want to display those.
So the .include element can be used to filter out unwanted properties from the result, and only display (i.e. include) those you are interested in. However, note that .include will also filter out items that do not have this property.
For example, to display all the properties annotating an item found.
//Find all items, and display the "name" and "repo" fields, as well as all properties associated with each item
items.find().include("name", "repo", "property.*")However, if you are only interested in a specific property (e.g. you just want to know the version of each item returned), you can filter out all other properties and only include the property with the key you are interested in:
//Find all items, and display the "name" and "repo" fields, as well as the key and value of the "version" property of each item
items.find().include("name", "repo", "@version")