The `output` clause

In the output clause, you can define which fields are to be included in the result. Moreover, you can use parameters to specify how the selected records are printed in the result.

For more information about records, see What is a record.

The `fields` parameter in the output clause

You can specify a fields parameter to name the fields that are printed for each record in the result. These fields can be data fields or technical fields.

Notes:

The data fields are present in the Wazi Deploy evidence files. They can be, for example, the name of an activity or an action, or the name or type of an artifact. The data fields are listed and explained in The evidence file.

The technical fields are stored in the records at indexing time or computed. For more information, see The technical fields in an output clause.

The following examples show how you can use this parameter in an output clause. In these examples, the select clause extracts all the records.

Printing of the following fields for all the records: the name field, the description field, and the key and value fields of the properties field.
```
select: all
output:
  fields: 
    name: true
    description: true
    properties: 
      key: true
      value: true
```
Printing of the data fields for all the records (default value):
```
select: all
output:
  fields: data
```
Printing of the technical fields for all the records:
```
select: all
output:
  fields: technical
```
Printing of both the data fields and the technical fields for all the records:
```
select: all
output:
  fields: all
```

The `format` parameter in the output clause

You can specify a format parameter to change how the search result is printed. The format parameter is not used alone. It requires the presence of at least one subparameter.

Each subparameter is followed by examples that show how you can use this subparameter in an output clause. In these examples, the select clause extracts all the records.

The flatten subparameter is used to flatten the hierarchy of the records on single lines.
- Result in a tree format (default value):
```
select: all
output:
  format:
    flatten: false
```
- Result on single lines:
```
select: all
output:
  format:
    flatten: true
```
- Result on single lines. The various levels of the hierarchy are separated by the value of field_separator. The default value is a dot.
  The various indexes are separated by the value of index_separator. The default value is [].
```
select: all
output:
  format:
    flatten: 
      field_separator: ';' 
      index_separator: '//'
```
The single_doc subparameter is used to print the result as a YAML list or as a list of YAML documents (separated by a line of three dashes (---)).
- Result in a list of YAML documents (default value):
```
select: all
output:
  format:
    single_doc: false
```
- Result in a YAML list:
```
select: all
output:
  format:
    single doc: true
```
The syntax subparameter is used to choose the syntax of the result.
- Result in a YAML format (default value):
```
select: all
output:
  format:
    syntax: yaml
```
- Result in a JSON format:
```
select: all
output:
  format:
    syntax: json
```
The indent subparameter is used to choose the indentation of the various levels in the result.
- Indentation of the levels by 3 characters in the result. The default indentation is 4.
```
select: all
output:
  format:
    indent: 3
```
The sort_keys subparameter is used to choose the sort order of the field names of the records in the result.
- No sort of the field names in the result (default value):
```
select: all
output:
  format:
    sort_keys: false
```
- Sort of the field names in the result:
```
select: all
output:
  format:
    sort_keys: true
```
The width subparameter is used to specify the maximum width of the lines in the result.
- Maximum line width of 500 characters. The default value is 1000.
```
select: all
output:
  format:
    width: 500
```

The `limit` parameter in the output clause

You can specify a limit parameter to limit the number of the records in the result.

The following examples show how you can use this parameter in an output clause. In these examples, the select clause extracts all the records.

No limitation to the number of the records in the result (default value):
```
select: all
output:
  limit: false
```
Limitation to 500 for the number of the records in the result:
```
select: all
output:
  limit: 500
```

The `unique` parameter in the output clause

You can specify a unique parameter to filter the duplicates in the result.

You can use the unique parameter in various ways in the output clause:

If you want to apply this parameter to the whole records in the result, enter it directly under output. In this case, you set unique to true or false.
The following examples show how you can use this parameter in an output clause. In these examples, the select clause extracts all the records.
- Printing of only the first occurrence of an identical record in the result:
```
select: all
output:
  unique: true
```
- Printing of all the records, including repeated identical records (default value):
```
select: all
output:
  unique: false
```
If you want to apply this parameter to the some fields in the result, enter it under the fields clause.
The following example shows how you can use this parameter in the fields clause of an output clause. In this example, the select clause extracts all the records
- Printing of only the first occurrence of a record that has a given name and description:
```
select: all
output:
  fields: 
    name: unique
    description: unique
    properties: 
      key: true
      value: true
```

If you want to associate the uniqueness characteristic of a field with a subset of data related to another field of the record, enter the unique parameter under the fields clause and use aggregation keywords, which you can combine, on another field of the record.

For example, for each record that has a unique name and type, you can print a subset of data related to the record length (record_length field). With the count keyword, you print the number of records that have a record_length field. With the min keyword, you print the minimum value of the record length. With the max keyword, you print the maximum value of the record length.

select: all
output:
  fields: 
    name: unique
    type: unique
    record_length: count min max

The following table lists the aggregation keywords and what they print.

Aggregation keywords	Description
`count`	Number of records that have a value for the specified field
`number`	Number of the distinct values found for the specified field
`list`	List of the values found for the specified field
`values`	List of the distinct values found for the specified field
`min`	Minimum value found for the specified field
`max`	Maximum value found for the specified field
`avg`	Average value found for the specified field
`first`	First value found for the specified field (same effect as `true`)
`last`	Last value found for the specified field
`sum`	Sum of the values of a field for all the selected records

The `unfold` parameter in the output clause

You can specify an unfold parameter to unfold the hierarchy of the selected records in the result.

The following examples show how you can use this parameter in an output clause. In these examples, the select clause extracts all the records.

Printing of the collapsed hierarchy of the records in the result (default value):
```
select: all
output:
  unfold: false
```
Printing of the expanded hierarchy of the records in the result:
```
select: all
output:
  unfold: true
```
Printing of the expanded hierarchy of the records down to the third level in the result:
```
select: all
output:
  unfold: 3
```
Printing of up to 3 levels of subrecords of the selected records, and 4 levels of parents of the selected record.
Note: 3 levels of subrecords of the parent records will be printed. The last number (4 in the example) is effective only if the ymli_parent technical field is set in the output fields definition.
```
select: all
output:
  unfold: 
  - 3
  - 4
```
Printing of up to 3 levels of subrecords of the selected records, 4 levels of parents of the selected record, and 2 levels of subrecords of the parent records.
Note: The last two numbers (4 and 2 in the example) are effective only if the ymli_parent technical field is set in the output fields definition.
```
select: all
output:
  unfold: 
  - 3
  - 4
  - 2
```

The `root_fields` parameter

You can specify a list of fields to be displayed for the selected records and another list of fields to be displayed for their subrecords. Subrecords are found when the selected records are expanded with the unfold parameter. The selected records are the root fields.

The root_fields parameter accepts the same attributes as the fields parameter.

If root_fields is not indicated, the fields parameter is used for the printing of the fields of the selected record and for the printing of the fields of the subrecords.

The following examples show how you can use this parameter in an output clause. In this example, the select clause extracts all the records.

Printing of the data and technical fields for the root records and printing of the data fields only for the subrecords:
```
select: all
output:
  unfold: true
  root_fields: all
  fields: data
```

The technical fields in an output clause

In the output clause, you can specify two types of technical fields:

The technical fields that you can enter in the select clause. For more information, see Using technical fields in a select clause. These fields are stored in the records.
The technical fields that are computed.

The following table lists and describes the names of the computed technical fields that you can use in the fields or root_fields clause of the output clause. These fields cannot be specified in the select clause.

Field names	Description
`ymli_stored_fields`	All the fields that are stored in the selected record. They correspond to the data and technical fields that you can specify in the `select` clause.
`ymli_stored_technical_fields`	All the technical fields that are stored in the selected record. They correspond to the technical fields that you can specify in the `select` clause.
`ymli_all_fields`	All the data and technical fields of the selected record.
`ymli_data_fields`	All the data fields of the selected record. These fields come from the evidence files.
`ymli_composite_data_fields`	All the data fields that have subfields.
`ymli_terminal_data_fields`	All the data fields that do not have subfields.
`ymli_technical_fields`	All the technical fields of the selected record.
`ymli_full_location`	Full location of the file that contains the selected record. It is constituted of the entire path to the evidence file, starting with the root folder that contains the evidence file (data by default). It also indicates the start line number and, after two dots (`..`), the end line number of the record in the file. Example: data/ansible/zos_host_01_evidences_20230128123021.yml:460..462
`ymli_location`	Location of the file that contains the selected record. It is constituted of the path to the evidence file, relatively to the root folder that contains the evidence files. It also indicates the start line number and, after two dots (`..`), the end line number of the record in the file. Example: ansible/zos_host_01_evidences_20230128123021.yml:460..462
`ymli_full_file_path`	Full path to the file that contains the selected record. It starts with the root folder that contains the evidence files (data by default). Example: data/ansible/zos_host_01_evidences_20230128123021.yml
`ymli_file_path`	Path to the file that contains the selected record, within the root folder that contains the evidence files (data by default). Example: ansible/zos_host_01_evidences_20230128123021.yml
`ymli_parent`	The parent record of the selected record. Under the `ymli_parent` clause, you can define the fields of the parent records that you want to print.
`ymli_selection`	A counter that counts the selected records. It starts from 1.

The following examples show how you can specify a technical field in the fields and root_fields parameters of an output clause. In these examples, the select clause lists all the records.

Printing of all the stored fields (data and technical fields) for all the records:
```
select: all
output:
  fields: 
    ymli_stored_fields: true
```
Printing of some parent fields. The result of the following example prints all the data fields of the selected records and the name and description fields of their parent records:
```
select: all
output:
  fields: 
    ymli_data_fields: true
    ymli_parent: 
      name: true
      description: true
```
Printing of the different fields for the selected records and their subrecords:
- For the selected records (root_fields), the following fields are printed: record counter (ymli_selection), level of the record relatively to the root in the YAML tree (ymli_level), and data fields (ymli_data_fields).
- For the subrecords (fields), the following fields are printed: level of the subrecords in the YAML tree (ymli_level), and data fields (ymli_data_fields).
```
select: all
output:
  unfold: true
  root_fields: 
    ymli_selection: true
    ymli_level: true
    ymli_data_fields: true
  fields:
    ymli_level: true
    ymli_data_fields: true
```

Sorting and grouping the records in the result

You can sort the records, group them, or sort and group them in the result.

You sort the records by entering numbers that correspond to the sort criteria. A positive number means that the sort is increasing. A negative number means that the sort is decreasing.
In the following example, you display the name, type, and length fields of the records. The records are first sorted according to the increasing alphabetical order of their names (name: 1). Then, the records that have the same name are sorted according to the decreasing alphabetical order of their type (type: -2).
```
select: all
output:
  fields: 
    name: 1
    type: -2
    record_length: true
```
The following lines show the simplified example of a result that can be returned by the query.
```
---
name: name1
type: Library
record_length: 3
---
name: name1
type: Library
record_length: 5
---
name: name1
type: Library
record_length: 2
---
name: name1
type: Library
record_length: 10
---
name: name2
type: Zip
record_length: 20
---
name: name2
type: Zip
record_length: 10
---
name: name2
type: Library
record_length: 51
---
name: name2
type: Library
record_length: 0
```

You group the records by entering a group attribute on the fields to be grouped. Then the result is not displayed as a list of individual records at the same level. The group fields constitute the first level and they embed the other fields that belong to the group.

In the following example, you specify that the records are to be grouped if they have the same name and type. The record length of each found record is to be embedded under these groups.

select: all
output:
  fields: 
    name: group
    type: group
    record_length: true

The following lines show the simplified example of a result that can be returned by the query.

The records that are included in a group are introduced by ymli_data.

---
name: name1
type: Library
ymli_data:
	- record_length: 3
	- record_length: 5
	- record_length: 2
	- record_length: 10
---
name: name2
type: Library
ymli_data:
	- record_length: 51
	- record_length: 0
---
name: name2
type: Zip
ymli_data:
	- record_length: 20
	- record_length: 10

In the following example, you use the aggregation keywords to display information that is related to the record length.

select: all
output:
  fields: 
    name: group
    type: group
    record_length: true count min max

The following lines show the simplified example of a result that can be returned by the query.

The records that are included in a group are introduced by ymli_data.

---
name: name1
type: Library
record_length|count: 2
record_length|min: 0
record_length|max: 51
ymli_data:
	- record_length: 51
	- record_length: 0
---
name: name1
type: Library
record_length|count: 4
record_length|min: 2
record_length|max: 10
ymli_data:
	- record_length: 3
	- record_length: 5
	- record_length: 2
	- record_length: 10
---
name: name2
type: Zip
record_length|count: 2
record_length|min: 10
record_length|max: 20
ymli_data:
	- record_length: 20
	- record_length: 10

In the following example, you specify that only the groups are to be displayed in the result (group_only: true). So the embedded data will not be displayed.

select: all
output: 
  group_only: true
  fields:  
    name: group
    type: group
    record_length: count min max

The following lines show the simplified example of a result that can be returned by the query.

---
name: name1
type: Library
record_length|count: 2
record_length|min: 0
record_length|max: 51
---
name: name1
type: Library
record_length|count: 4
record_length|min: 2
record_length|max: 10
---
name: name2
type: Zip
record_length|count: 2
record_length|min: 10
record_length|max: 20

You can sort and group the records in the result.
The following example is constituted of two embedded group levels.

The records are first sorted by the increasing alphabetical order of their names. Each unique name constitutes the first level of a group (name: group 1).

The second level of each group is constituted of the values of the types, which are sorted according to their decreasing alphabetical order (type: group -2).

Inside both of these groups, the record lengths are displayed and include their count number, minimum value, and maximum value (record_length: true count min max). You also specify that the record length constitutes the third sort criterion and that the record lengths are sorted according to their increasing numerical order (record_length: 3),
```
select: all
output:
  fields: 
    name: group 1 
    type: group -2 
    record_length: 3 true count min max
```
The following lines show the simplified example of a result that can be returned by the query.
The records that are included in a group are introduced by ymli_data.
```
---
name: name1
record_length|count: 4
record_length|min: 2
record_length|max: 10
ymli_data:
  - type: Library
    record_length|count: 4
    record_length|min: 2
    record_length|max: 10
    ymli_data:
	- record_length: 2
	- record_length: 3
	- record_length: 5
	- record_length: 10
---
name: name2
record_length|count: 4
record_length|min: 0
record_length|max: 51
ymli_data:
  - type: Zip
    record_length|count: 2
    record_length|min: 10
    record_length|max: 20
    ymli_data:
	- record_length: 10
	- record_length: 20
  - type: Library
    record_length|count: 2
    record_length|min: 0
    record_length|max: 51
    ymli_data:
	- record_length: 0
	- record_length: 51
```

The output clause

The fields parameter in the output clause

The format parameter in the output clause

The limit parameter in the output clause

The unique parameter in the output clause

The unfold parameter in the output clause

The root_fields parameter

The technical fields in an output clause

Sorting and grouping the records in the result

The `output` clause

The `fields` parameter in the output clause

The `format` parameter in the output clause

The `limit` parameter in the output clause

The `unique` parameter in the output clause

The `unfold` parameter in the output clause

The `root_fields` parameter