%20small.png)
Content Links
Dataset
The first step is to choose whether you want to look for certain Actions or if you want to search for certain attribute changes in the Attribute History.
Model (If Querying Attribute History)
If you chose "Attribute History" for your dataset, you’ll have an available input for selecting a job model as part of simplifying the query. (If you chose "Actions" for your dataset, you won't have this option and you can move on to the Filter section below.)
Select the appropriate job model that is used by the job(s) you want to retrieve Attribute History from before proceeding to the Filter.
Filter
You can filter based on values of the Actions or attribute changes themselves, which job you want to search in, the user responsible for the Action or attribute change, and the time frame the Action or attribute change took place.
There is no negation for this filter, so you can only filter based on what these things are, not based on what they aren’t.
For Actions, Jobs, Users, and Time, you are setting a specific value. For Attribute History, there are a few more steps. You can choose the attribute you're looking for (in the above screenshot, we've chosen the "done" attribute) and specify the value it was changed to by choosing the operators "equals," "is less than," "is less than or equal to," "is greater than," or "is greater than or equal to." If you're not looking for any values in particular and want to see all the changes to that attribute, you may select "Does not Matter" from the dropdown.
This Filter works by using “AND” and “OR” logical statements. Remember that using the “AND” grouping will require that all the conditions you set in this group must be true. If even one condition isn’t met, then that Action or attribute change will not show up in the results. In the above example, the query will only return the instances where the specified user changed "done" to true in the job specified. All other attribute changes made by this user will be ignored, all other attribute history in the specified job will be ignored, and all other changes to the done attribute will be ignored. All three need to be true about the attribute change in order for it to show up in the results.
Using “OR” grouping means that at least one (or more) of the conditions in this group must be true. If the Action or attribute change meets only one condition in this type of grouping, it will still show up in the results. This time, using the same conditions as our last example but changing the grouping from "AND" to "OR," all the attribute changes by the same specified user will be in the results, as well as all the attribute history in the same specified job and all the changes to the done attribute where done was marked as true (within the specified job model in the previous input). That's why we see more results with this filter than when we put those conditions in the "AND" grouping. Using "OR" grouping is not as restrictive.
You can have nested statements, but overall the available nesting structure allows several “AND” groupings inside one large “OR” grouping. So you’ll have groupings where all the conditions must be met, but as long as one of these groupings has all its conditions met, then that Action or attribute change will show up in the results.
If using nested statements, be sure to keep it simple. If there are too many nested statements, you will see a warning when you try to run the query: "Query parameters are too complex, please simplify the query and try again." At this point, you may break down the statement into smaller queries and run several queries separately. (The five "AND" groupings in the screenshot above could all be run separately.)
Maximum Results
This allows you to control how many Actions or attribute changes, at most, will be retrieved. Typically the more recent Actions / attribute changes are retrieved first.
The larger you make the maximum, the more results the software will retrieve, and, consequentially, the slower its retrieval will be. This may not be as noticeable until you set the maximum results limit to about 10,000.
If the number of results is equal to the "# Maximum Results" you have specified, it is likely that there were more results that were not retrieved due to this limit. To retrieve the rest of the results, since they are typically retrieved in order from most recent to oldest, you can set a timeframe to adjust the query so that it retrieves the remaining, older results.
Use the day that the oldest results from the first query are from as the beginning of the timeframe with an older date as the end of the timeframe. Then you can re-run the query to see how many results you get. Keep doing this until you get a number of results that are below the maximum results threshold.
Running The Query
Once you’ve built your query, click “Run Query” to retrieve the results.
The results will display the job name (which links to the job), the avatar of the user responsible for the Action or attribute change, the name of the Action or attribute that was changed with the corresponding value below it (in parentheses) if there is one, and the date this Action or attribute change took place.
You can change any part of the query and click “Re-run Query” to run the new query, or you can click “Download Results” to download a CSV file with a few more details. This export provides the results in a format that is easier to use for data manipulation and analysis.
Thanks for reading! For any questions, reach out to our Support team at 717-430-0910 or support@katapultengineering.com. How can we improve our documentation? Let us know in the comments below!