Show Or Hide Columns
Projections
Orgvue’s API allows you to define the properties you want to see by supporting a projection object.
This functionality extends to being able to select a Projection Mode and sorting property columns for the Async Export API
How to use projections
You can filter your dataset properties in JSON format using a schema like the following:
{
"projection": {
"_id": 1,
"_modifiedAt": 1,
"role": 1,
"currentsalary": 1
}
}
The content of a projection object tells the export API which properties to include (or exclude).
To include a column a value of 1 is supplied.
No other values are supported by the projection object in the Sync Export endpoint and any properties not included in the projection object will be excluded from the export
In Add Mode when using the Async Export Endpoint projection mode (see below) only, the value 0 may be used to exclude a column.
If a projection is not supplied then all property columns will be returned by default.
The two projection modes
For the Async Export API only
You can select one of the two available projection modes, "add" or "replace", by setting the projectionMode attribute.
Add mode
When projectionMode is set to "add", all properties are included by default.
The value 0 may therefore be used to remove a property.
Other numeric values can be supplied to sort the columns (see below).
This is the default mode for export output queries.
Replace mode
When projectionMode is set to "replace", no properties are included by default.
Properties are included only if a non-zero value is provided.
Other numeric values can be supplied to sort columns (see below).
This is the only behavior currently available for non-export queries.
Sort order
For the Async Export API only
The sort order of properties (columns) can also be specified
{
"projection": {
"_id": 0.1,
"_modifiedAt": 0.2,
"role": 2,
"currentsalary": 2,
"date_of_birth": 0
},
"projectionMode": "add"
}
In this case, a non-zero value indicates a column's inclusion as well as primary sort order.
If no projection is supplied then columns will appear in the order set by their sortOrder metadata.
As you can see, values are not limited to integers, and indeed negative numbers are permitted.
Columns are sorted from the lowest supplied value to the highest.
By default, properties take the value 1 for their primary sort order (this is relevant in the "add" projection mode).
Because of this, to force a column to appear before any other, values less than one may be used (either decimals or negative numbers).
If properties have the same primary sort value, their relative position in the sort reverts to their internal Orgvue sort order (defined by the _sortOrder property).
- To remove a column set the attribute to zero.
- Choose incrementing integers to order columns accordingly.
- Negative numbers and decimals are allowed, and columns returned in increasing order.
Default properties
When using either Export API if no projection is included then all properties will be returned by default
If any projection is included then only those properties explicitly included in projection will be returned
Example of using the add mode
For the Async Export API only
This is the default projectionMode for the Async Export API
In add mode, every column will be included in the response body by default.
Individual columns can be hidden or reordered based on the contents of projection object.
The add mode is useful for when you would like to only remove select columns for your results.
- set any columns you do not want to be returned to
0(zero). - set a sorting order for any of the dataset properties using the logic described in the sort order section
For example, given a people dataset you may wish to:
- hide the "salary" and "age" properties from appearing in your result
- set "employeeGrade" to be the first column that gets returned for each row of data
- set "directReports" and "department" to be the last columns that get returned for each row of data
In which case you should the following object to your request body:
{
"query": {
"output": {
"projection": {
"salary": 0,
"age": 0,
"employeeGrade": -1,
"directReports": 2,
"department": 2
}
},
"projectionMode": "add"
}
}
Example of using the replace mode
For the Async Export API only
In replace mode, every column will be hidden from the response body by default.
Individual columns can be made visible or reordered based on the contents of projection object.
The replace mode is useful for when you would only like to return a few select dataset properties from each row.
Setting the projectionMode attribute to replace will allow you to:
- set any columns you want to be returned to
1. - set a sorting order for any of the dataset properties using the logic described in the sort order section
In replace mode, at least one column needs to be included (via a non-zero value) for any data to be returned. An empty projection {} or a column set to 0 are invalid in this mode, and will produce an error response.
For example, given a people dataset you may wish to:
- show the "salary" and "age" properties in your result
- show "employeeGrade" and set it to be the first column that gets returned for each row of data
- show "directReports" and set it to be the second column that gets returned for each row of data
- show "department" and set it to be the last column that gets returned for each row of data
In which case you should the following object to your request body:
{
"query": {
"output": {
"projection": {
"salary": 1,
"age": 1,
"employeeGrade": -2,
"directReports": -1,
"department": 2
}
},
"projectionMode": "replace"
}
}