Getting started with Carrot
Carrot (Carrot Query Language) is the most powerful way to search, create and reference data across your ChartHop organization using custom or built-in functions and filters.
With Carrot you can:
- Create powerful calculations using company data to evaluate financial performance and capture valuable employee data analytics using smart fields.
- Filter your employee data for customizable visualizations using the Map, Datasheet, and Reports.
- Quickly reference employee data almost anywhere in the ChartHop platform including in the , Data sheet, Map, Reports, Custom fields, and app configurations.
One of Carrot's greatest values comes from its ability to enable users to build advanced structured queries, filters, and smart fields that perform calculations.
A simple query in Carrot consists of a field, followed by an operator, followed by one or more values or functions. For example:
This query will find all ChartHop users in the organization with the job title of "Director of Engineering". In this case, the query uses the title field, the EQUALS operator, and the value Director of Engineering.
For more complex queries, keywords can be used to filter data by more than one criteria. For example:
This query will find all ChartHop users in the organization with "director" somewhere in their job title and who started working before the date of January 1st, 2020. In this case, the query uses the title field, the COLON operator which functions as a Fuzzy search, and the value director as the first half of the query. Then, followed by the &&(AND) keyword the query includes the startDate field, followed by the LESS THAN operator, and then the value '2020-01-01'
The below examples illustrate how you might use Carrot when creating filters, queries, custom fields, etc.
Example | Searches for |
title:director | Everyone with "director" somewhere in their title. |
title="Director of Engineering" | The exact title "Director of Engineering". |
startDate<'2020-01-01' | Everyone who started before the date January 1st 2020. |
is:manager | All people managers. |
!department:sales,marketing | Everyone who is not in the Sales or Marketing departments. |
is:open daysOpen>90 | Open jobs that have been open for more than 90 days. |
To create a carrot query, you need to have a basic understanding of fields, operators, values, functions, and keywords. You can learn more about fields, values, functions, keywords, and operators below.
A field in Carrot is a word that represents a built-in field or a custom field that has already been defined in ChartHop. All fields are case-insensitive.
A field contains a reference to specific job, employee and organization data, allowing operations to be ran on it in order to perform calculations. For example:
The workAddressfield can be used as a reference to an employee's work address found in their employee profile.
Fields may also posses properties which are unique members of data belonging to the field's particular data type. For example:
city is a property of the workAddress field and has the value of "Oak Park".
An operator in Carrot is one or more symbols or words that compare the value of a field on its left with one or more values (or functions) on its right. The valuation of the clause will always result as true. For example:
This query uses the * (multiply) operator to evaluate the basic mathematical statement.
This query returns all records where department is engineering.
Carrot operators understand money-math and will automatically convert currencies when adding or subtracting two different currencies.
A keyword in Carrot is a word or phrase that does (or is) any of the following:
- Joins two or more clauses together to form a complex Carrot query.
- directs>0 && department:engineering
- Alters the logic of one or more clauses.
- directs>0 && !department:accounting
- Alters the logic of operators.
- department!="engineering"
- Has an explicit definition in a Carrot query
- department:engineering where: means"matches"
- workAddress.city:"Oak Park" where . refers to the property city of the field work address field
- Performs a specific function that alters the results of a Carrot query.
- tenure <= 3
Carrot contains a limited number of reserved keywords.
A function in Carrot appears as a word followed by parentheses, which may contain one or more explicit values or Carrot fields. All functions are case-insensitive.
A function performs a calculation on specific Carrot data or on the function's content (enclosed within its parentheses), such that the results retrieved by the function return as true, and then again by the clause in which the function is used. For example:
This query will return the base compensation of a person between the dates of January 7th, 2017 and January 8th, 2022.
An aggregator in Carrot appears as a word followed by curly brackets, which contains an expression. All aggregators are case-insensitive.
An aggregator performs a calculation on an expression and returns a Number value based on the aggregator's logic. For example:
This query will return the total number of jobs in the engineering department in the ChartHop organization. All non-numeric values are discarded.
Carrot understands many common data types, including standard data types such as Number and String, as well as a number of ChartHop-specific data types such as Money and Comp.
Carrot has a list of reserved characters:
space (' ') - + = . : ? | * / % [ ]
These characters are reserved for use in operations and keywords. If you wish to use these characters in queries, you need to surround them with quote-marks. You can use either single quote-marks ' or double quote-marks ".
For example:
Search for special characters in text fields is limited.
All data access in Carrot is permission controlled, according to ChartHop Access Levels, and so query results may vary between users depending on their level of permissions.
