Commands for comparing and applying objects
You can compare and apply Compose objects using the compare_csv and apply_csv CLI. Before performing any of these operations, it is strongly recommended to review the topic(s) that discuss CSV file structure and the impact of missing columns and/or values on the target environment. For example, before applying changes to a Model, review the "Migrating the Model" topic.
Comparing objects
Comparing the model to be imported with the existing project model allows you to view and optionally edit the proposed changes before applying them.
When you run the Compare command, the structure of the CSV output files will be identical to the export output files, but with the addition of Change Type and Action columns at the end. Note that as the Apply command only supports ADD operations, the only value in the Change Type column will be ADD.
If a column or value was deleted in the source environment, the Action column will contain the value "IGNORE". This tells Compose not to delete the corresponding column/value in the target environment when the Apply command is run. You can delete the "IGNORE" before running the Apply command to force the deletion of the corresponding column/value in the target environment. However, as the Apply command does not support DELETE operations, deleting the "IGNORE" before running the Apply command will have no effect.
Compare guidelines:
- Unchanged objects will not be written to the output file(s).
- If there was no changes at all to any of the object types, an empty output file will only be created if you include the --create_files_even_when_no_diff parameter in the command (see below).
- For Boolean fields, values are True/False
- Data type is Compose's logical type.
- For model, the attributes writing order is according to the new ordinal in the entity.
- Mapping metadata, attributes domain and entity order is alphabetical in the CSV file.
- Relationship order is by entity name (alphabetical) and according to their order in the entity.
- For mapping, the listed order is:
- Alphabetical for mapping names (e.g. Map_Orders follows Map_Customers)
- According to target columns (model ordinal) within a mapping.
- Within a mapping, FD (From Date) could be one of the rows.
- Source columns which are not mapped to anything will not be included in the output file.
- If the model is not valid, the Compare command may fail.
Compose CLI requires Administrator permission. To grant Administrator permission, select "Run as administrator" when opening the command prompt. All commands should be run from the Compose bin directory (C:\Program Files\Qlik\Compose with a default installation).
Command syntax
ComposeCli.exe compare_csv --project project_name --infolder folder --changes_folder folder [--create_files_even_when_no_diff]
Parameters
Parameter | Description |
---|---|
--project | The name of the project. |
--infolder | The folder containing the exported CSV files. |
--changes_folder | The folder to where the change files will be written. The file names will be identical to the exported CSV files, but with a _changes suffix (e.g. entity_changes.csv). |
--create_files_even_when_no_diff |
Use this parameter if you want a template output file to be created when there are no differences (e.g. an empty entity_changes.csv file containing only the header columns). This may be useful, for example, if you wish to manually create a changes file. |
Example
ComposeCli.exe compare_csv --project ProjectEmpty --infolder "C:\1" --changes_folder "C:\2" --create_files_even_when_no_diff
Applying objects
Once you are satisfied with the proposed changes, you can then apply them to your project.
Apply guidelines:
- If a column is missing on ADD, then the action will be as described in the topic discussing the object elements.
- By default, all changed object definitions will be added. To filter out rows or columns, edit the outputted CSV file as needed. For example, to only apply changes to a specific Data Mart, delete all of the other Data Marts' rows.
- Any non-standard field name headings, should be renamed in the CSV to the Compose standard.
- Column order is insignificant as the columns will be ordered by name (case insensitive).
- For Boolean fields, accepted values are Yes/No, True/False, 1/0 (case insensitive)
- Data type is Compose's logical type.
-
Relationship details override the underlying attributes information (e.g. History Type, Is Key, etc.).
Information noteAttributes that are marked as relationships will be skipped on import as they derive their data type from the relationship.
- All CSV files are optional in the folder.
- For mappings, the apply operation will fail in the following scenarios:
- The model is not valid.
- The target does not exist in the model.
- The mapping attribute does not exist in the model (after applying attributes.csv)
- The Compose database object does not exist.
- If the source schema, table, view or query does not exist, it will be validated after the Apply operation .
Run the following command from the Compose bin directory:
Command syntax
ComposeCli.exe apply_csv --project project_name --changes_folder folder
Parameters
Parameter | Description |
---|---|
--project | The name of the project. |
--changes_folder | The folder containing the change files written by the compare command. |
Example
ComposeCli.exe apply_csv --project ProjectEmpty --changes_folder "C:\1"