Knowledge Base

Skill Query API

The Skill Query API allows programmatic access to execute Skill Query queries. The endpoint is read-only.


Endpoint

/2.0/skillquery


Objects used by this API

Skill Query Request object

Defines the JSON object that must be provided in the HTTP request body when calling the Skill Query API. The object can have these properties:

Name Data type Description
query string The Skill Query statement to execute


Skill Query Result object

Defines the JSON object that the API will return in the HTTP response body. The object can have these properties:

Name Data type Description
status string Returns "success" if the query was successful.
data ResultSet object A Skill Query Result Set. See below.

ResultSet object

A ResultSet object is returned as the value of the "data" property of the API response.


Name Data type Description
columns array of Column objects Contains metadata about each of the result table columns.
rows array of Row objects Contains each result table row.
totalRows integer The number of rows that the query produced. May be less than the number of rows that are returned in the ResultSet, due to pagination. 
offset integer The pagination offset that applied to this query. 
limit integer The pagination limit that applied to this query, or null if no limit. 
accessRestrictions boolean If "true", indicates that some rows or values may have been suppressed due to security restrictions.


Column object

The Column object is a property of the Skill Query "data" object 

Name Data type Description
path array Identifies the property that was requested from the Skill Query data model, relative to the query's root collection.
For example, in the query "FIND person skills SHOW person.team, skillLevel", the path for the first column would be ["person", "team"]. This refers to the "team" property of the "person" property of the "person skills" collection.
title string The display name for the column.
type enum The main data type for values in this column. One of:
  • boolean
  • date
  • decimal
  • integer
  • percentage
  • rating
  • reference
  • richtext
  • shorttext
  • text
  • timestamp
  • tuple
processingFunction enum (optional) Indicates whether any special processing applied to the values in this column. One of:
  • none : No special processing
  • delta : Numbers represents the difference between a current value and an earlier value
  • percent-change : Numbers represents the percentage difference between a current value and an earlier value
groupingValue string

(optional) If there are multiple columns with the same property path, contains the value that disambiguates this column from the others.

For example, the query "FIND person skills SHOW person, skillLevel BY skill" would return multiple "skillLevel" columns, one for each skill. The groupingValue will contain the name of the skill.

Row object

The Row object is a property of the Skill Query "data" object 

Name Data type Description
values array of Value objects The values for this result table row

Value object

The "values" property of the Row object contains an array of Value objects. The properties of a Value object depend on the data returned. Therefore it is not guaranteed that all of the following properties will be available.

Name Data type Description
type enum Data type. One of:
  • boolean
  • date
  • decimal
  • integer
  • percentage
  • rating
  • reference
  • richtext
  • shorttext
  • text
  • timestamp
  • tuple
data string|integer|float|boolean|null The raw value
collectionName string The display name of the Skill Query collection that this value came from (for example "person skills")
url string The URL of the related entity (if applicable)
For example, if this value represents a person's name, the "url" property will contain the URL for viewing that person's dashboard in Skills Base.
id string|integer The unique identifier of the related entity (if applicable)
For example, if this value represents a person's name, the "id" property will contain the ID of the person record.
colorHex string The color associated with this value (if applicable).
For example, if this value is a skill rating, the "colorHex" property will contain the color used when visualizing that rating in Skills Base dashboards. 
disposition enum Communicates additional semantics for the value (if applicable). One of:
  • delta-value : When the value represents the difference from some starting value (so should be rendered with a +/- prefix).
  • no-value : When no value exists. "data" will be null.
  • redacted-value : When a value exists, but cannot be shown due to restrictions. "data" may be null, or may contain placeholder text such as "Hidden Person"
  • no-answer : When the requested property is unavailable due to restrictions. A value may or may not exist in the underlying storage. "data" will be null.
html string A HTML representation of the related entity (if applicable).
For example, if the value represents a person's name, the "html" property may contain markup for displaying that person's user avatar.
childValues array of Value objects If the value represents a multi-value property, this contains an array of the set of sub-values that make up this value.
For example, in the query "FIND skills SHOW name, parentCategories", the second column will contain a list of the skill's category ancestry.
In this scenario, "data" will contain a (possibly truncated) display string such as "Category A > Category B", while "childValues" will contain a full Value object describing each category in the set.
suggestedSeparator string If the value represents a multi-value property, this contains the recommended string for concatenating the items in the list, when rendering a UI.
For example:
  • For the property "person.roles", a comma is a suitable separator: Role A, Role B
  • For the property "team.ancestry", a greater-than symbol is more suitable since it denotes a path-like hierarchy: Root Team > Sub-team


Methods

POST /skillquery

Executes a Skill Query query.

The HTTP request body must be a Skill Query Request object (see above).