Search basics (v3)

Cloud Talent Solution allows users to search against jobs you have stored in Cloud Talent Solution's index. This document walks you through the various search and related offerings of Cloud Talent Solution.

Search requests

To make a job search request, send a POST request to the jobs:search endpoint, passing the search data in the body.

Required fields

The following field is required:

  • searchMode: Specifies the type of job search to apply. Options are:

    • JOB_SEARCH: This is the default, and recommended, search mode. All jobs are searched against. The most relevant jobs are returned in the order of relevance to the search query.
    • FEATURED_JOB_SEARCH: Searches only for jobs with a promotionValue greater than 0. Results are ordered by the highest promotionValue first; in the case of a tie, relevance is used to decide position. See Featured Jobs for more info.

Commonly used fields

  • JobQuery: Specify the job criteria to match against. These include location, job categories, employment types, text queries, companies, etc. See Search Filters for more information.

  • requestMetadata: Contains user and session information for this search request. See RequestMetadata for details.

  • jobView: Defines the number of fields that are returned for each matching job. Can be JOB_VIEW_SMALL (the default), JOB_VIEW_MINIMAL, or JOB_VIEW_FULL. Descriptions for each option are in the JobView reference.

  • orderBy: The sort order for returned jobs. See the reference for allowed values. The default is to sort by relevance, descending (RELEVANCE_DESC).

Relevance thresholding and location/category broadening

To return a higher number of jobs for your searches, the following two fields loosen the restrictions on relevance:

  • enableBroadening: Setting this to true loosens the restrictions on location and job category of the search request, in order to return more results. For example, if a search request specified jobs within a 2 mile radius of Anytown, WA, setting this flag to true may also return jobs from NextTownOver, WA as well.

  • disableKeywordMatch: This flag is false by default. Setting this flag to false allows Cloud Talent Solution to append the jobs that are relevant to this search query with jobs that also match the exact query string in the title or description.

RequestMetadata

Every search and histogram request should include a RequestMetadata object. This object contains information about the user initiating the search.

There are a few reasons this object is important:

  • User consistency. Cloud Talent Solution runs several versions of the underlying models simultaneously in an effort to improve search relevance. Fill in this field to ensure a job seeker has a consistent experiences. Cloud Talent Solution ensures that a job seeker (identified by userId, sessionId, and domain) has a consistent experience. Note: These fields should be obfuscated.

  • Search improvements.The tuning algorithms are based on the information provided in the RequestMetadata fields along with the job seekers' data you provide. This improves search result relevance.

Search operators

Operator Description
( ) Groups one or more keywords together.
AND Searches for results relevant to the keywords or groups of keywords on both sides of the operator.
OR Searches for results relevant to the keyword or group of keyword(s) on either side of the operator.
NOT Excludes results relevant to the keyword or group of keyword(s), in parentheses, immediately following the operator.
- Excludes results relevant to the keyword or group of keyword(s) appended to the operator.

For example:

  • "software OR java" returns jobs with either "software" or "java" in their metadata.

  • "software" -java returns jobs relevant to "software" but excludes jobs that are relevant to "java".

  • "(software OR java) AND (marketing)" returns jobs relevant to both "software" and "marketing", and jobs that are relevant to both "java" and "marketing".

Job seeker query

Search terms can also be detected as actual job related entities. For example, if the query was for 'intern', Cloud Talent Solution would treat this as the employment type "INTERN" and filter on jobs that only had the EMPLOYMENT_TYPE - INTERN. Therefore, even if intern was necessarily in the job description, it wouldn't be returned if the employment type for that job was set to something else.

Troubleshooting

Each search request generates a unique search requestID in our system that is used to track the parameters of that search as well as the response. This is crucial in troubleshooting issues related to specific search, CRUD requests, and should be appropriately logged. The requestId is returned inside the ResponseMetadata field in the search response body. or the associated CRUD call response object.

For support issues that relate to relevance, search inquiries, indexing inquiries, etc., please file a ticket with our support team, and include relevant request ids or request themselves.

Result counts

The result count is used to communicate the number of search results to the job seeker. This doesn't always correspond to the histogram results or the actual number of jobs returned. Job Search returns a maximum of 5000 jobs.

Pagination

By default, Job Search returns 100 results per page (or fewer, if the total number of results is less than 100). You can implement pagination using the fields associated with this feature.

  • pageSize: The number of results returned per page.
  • nextPageToken: A unique token, returned with the results of each page of search results, that specifies the starting position for the next page of results. This field is left empty if there are no more results.
  • offset: Specifies the offset between the relevance ranking of the job returned at the top of a given page and 1 (the most relevant Job returned). As an example, a user performs a search and pageSize is set to 10. The first page returns the #1 job at the top, therefore the offset value for this page is 0. The next page returns job #11 at the top; offset for this page is 10.

Set the page size to 20 results or less to avoid latency issues. As a best practice, issue a separate search call per page rendered to the job seeker. The alternative, a single search call to return a larger number of jobs and paginating on the client side, impedes the ability of the machine learning model to learn accurately through the Jobs Analytics Framework.

Spell checking

Spell check is a feature of Cloud Talent Solution search request that accounts for potentially misspelled search terms, corrects them and returns results based on the corrected query. For example, when spell check is enabled, if a job seeker searches for "manaer" instead of "manager", Cloud Talent Solution returns jobs for "manager". Spell checking can be enabled/disabled by setting the disableSpellCheck field of the JobQuery. If spell checking is enabled, the corrected query can be found in the search response, in the spellResult field.