Skill Query

Skill Query is a purpose-built language for producing powerful custom reports from your Skills Base data.

Editor tips

While you're entering a query:

• Press tab for hints about what you can type next.

• Press esc to make the hints go away.

• Press return to run the query.

• Press shift+return to add a new line without running the query.

• To make your queries easier to read, you can add spaces, tabs and line breaks as desired. They won't affect the interpretation of the query.

Query examples

Search any of the Skills Base directories using find. Select which details to return using show.

    find skills

    find skills show name, category

    find skills show name, category, category.parent

    find skills show name, parentCategories

    find people
    show name, team, location

Filter the results using where.

    find skills where category is 'Component assembly'

    find skills where one of parentCategories is 'manufacturing skills'

    find people
    where team.name starts with 'Engineering'
    show name, team, location

    //List people who aren't assigned to any team
    find people where team is blank

    //Search a multi-value property
    find people where one of roles matches 'Senior %'
    show name, roles

If your organization uses Custom Fields, these are treated the same as built-in fields with Skill Query. In these examples, a custom Person field has been defined called “favorite color”.

    find people
    where team is 'Engineering team'
    show name, favorite color

    find people where favorite color is 'Blue'

Look up individual skill level, interest level and competency ratings by searching person skills. You can use skillLevel.self or skillLevel.supervisor to refer to Self or Supervisor ratings specifically. On its own, skillLevel refers to averaged ratings.

    // This is similar to a Report Builder report in 'Assessment data' mode
    find person skills
    where person.team is 'Engineering team' and skill.category is 'Workplace safety'
    show person, skill, skillLevel

    // This is similar to a Report Builder report in 'People' mode
    find person skills
    where person.team is 'Engineering team' and skill.category is 'Workplace safety'
    show person, skillLevel by skill

Ratings are automatically averaged across all people who meet the query criteria.

    // The Engineering Team's average skill level (using supervisor ratings) for all skills possessed by team members.
    find person skills
    where person.team is 'Engineering team'
    show skill, skillLevel.supervisor

    // The Engineering Team's average competency (using self ratings) for all skills possessed by team members.
    find person skills
    where person.team is 'Engineering team'
    show skill, competency.self

    // The average level of Workplace Safety competency broken down by location.
    find person skills
    where skill.category is 'workplace safety'
    show person.location, competency

    // The average level of Workplace Safety competency broken down by a custom field.
    find person skills
    where skill.category is 'workplace safety'
    show person.favorite color, competency

A where filter applies prior to averaging. To filter based on the results of the averaging stage, use if.

    // Show people in the Engineering Team whose overall average skill level is greater than 3
    find people
    where person.team is 'Engineering team'
    show person, skillLevel
    if skillLevel > 3

You can also view skill level, interest level and competency data from the perspective of a team or role with person skills using team data and person skills using role data. Unlike person skills, these only show ratings for the skills which are assigned to the team or role entity, or that have targets set for that entity. Targets applied here are the targets set at the team or role level, which may not match a person's active targets.

    // Show people in the Engineering Team with their skill level for each Engineering Team skill.
    find person skills using team data
    where team is 'Engineering team'
    show person, skill, skillLevel

    // Show all people with the Developer role, and the extent to which they are meeting Developer targets.
    find person skills using role data
    where role is 'Developer'
    show person, competency

Get the number of matching records using count.

    // Find out how many people there are in the organization
    find people show count

    // Find out how many people are in each team
    find people show team, count

    // List teams containing less than 5 people
    find people
    show team, count
    if count < 5

    // For each skill, count how many people have a rating greater than 3
    find person skills
    where skillLevel > 3
    show skill, count

Control the order of results using sorted by and optionally limit the output using results.

    //Get the top 5 highest-skilled teams
    find person skills show person.team, skillLevel
    sorted by skillLevel descending
    results 1 to 5

Use by to break down a result column into multiple columns.

    // Ratings with people as columns, one row per skill. Similar to a Heat Matrix report.
    find person skills
    where person.team is 'Engineering team'
    and skill.category is 'Component assembly'
    show skill, skillLevel by person

    // Counts with ratings as columns, one row per skill. Similar to a Capability Matrix report.
    find person skills
    show skill, count by skillLevel

Use one of to find an item in a multi-value set, such as a team's ancestry.

    // Find skills of the people in team "Technical Services" and all its sub-teams
    find person skills
    where person.team.name = "Technical Services" or one of person.team.ancestry.name = "Technical Services"
    show skill

Use with to filter one data collection using criteria from other data collections.

    // Find people with a skill level greater than 4 in 'autocad' who ALSO have a
    // skill level greater than 3 in 'equipment maintenance'
    find people
    with person skills where
    skill = ‘autocad’ and skillLevel > 4,
    skill = ‘equipment maintenance’ and skillLevel > 3
    show name, location

Apply a weight to each criterion if you want to include results that match some, but not all of your criteria. Request the score to see the quality of each match.

    // This is a People Finder-style query that will include partial matches after the full matches.
    find people
    with person skills where
    skill = ‘autocad’ and skillLevel > 4 weight 1.0,
    skill = ‘equipment maintenance’ and skillLevel > 3 weight 1.0
    show name, location, score

View a snapshot of rating history by using as at. This is only available for the person skills collection. Note that if you reference properties from other collections, you will be examining current values. For example, if you filter your historical query based on person.team, the filter will consider current team membership, not membership as at the nominated date.

    // See ratings as they were on 1 January 2024
    find person skills as at '2024-01-01'
    where person = 'Allan McLean'
    show person, skill, skillLevel

Examine historical change events by using changes between. This is only available for a person skills query. The special timestamp property lets you see when the change occurred. Use delta and percent change to calculate rating differences.

    // List changes that have been made to the skill levels of people in the engineering team over
    // the past month. Include the relative change (+3) and the percentage change (+50%) from the
    // previous rating, where one exists.
    find person skills changes between '1 month ago' and 'now'
    where person.team = 'Engineering team'
    show person, skill, timestamp, skillLevel, delta skillLevel, percent change skillLevel
    sorted by person, skill, timestamp

Data model reference

Course mappings

Contains mappings between courses and the skill levels they help a person attain.

Courses

Reflects the contents of the organization's Courses Directory.

Locations

Reflects the contents of the organization's Locations Directory.

People

Reflects the contents of the organization's People Directory.

Person skills

Contains all the skills each person has ever been assessed against. The targets in this collection are the person's individual targets, which will be determined by their skillsetSource unless overridden by custom personal targets.

Person skills using role data

Contains all the skills currently assigned to each role, plus any skills which have active targets set for the role, for each person with that role. The targets in this collection are the role's targets.

Person skills using team data

Contains all the skills currently assigned to each team, plus any skills which have active targets set for the team, for each person in that team. The targets in this collection are the team's targets.

Qualification assignments

Contains mappings between people and qualifications.

Qualifications

Reflects the contents of the organization's Qualifications Directory.

Role skills

Contains all the skills currently assigned to each role, plus any skills which have active targets set for the role. The targets in this collection are the role's targets. This collection can be used to retrieve a role's targets or skill assignments even when there are no people with the role.

Roles

Reflects the contents of the organization's Roles Directory.

Skill categories

Contains the categories from the organization's Skills Directory.

Skills

Reflects the contents of the organization's Skills Directory.

Team skills

Contains all the skills currently assigned to each team, plus any skills which have active targets set for the team. The targets in this collection are the team's targets. This collection can be used to retrieve a team's targets or skill assignments even when there are no people in the team.

Teams

Reflects the contents of the organization's Teams Directory.

Training

Contains the courses which have been completed by each person, plus those that are currently recommended for each person. Recommendations may have been manually added by a person, or automatically generated based on targets and course mappings.