Histogram

Cloud Talent Solution allows you to get a histogram representation of the number of jobs associated with a given search. A histogram search returns a count of all jobs that match a particular query, broken down by the requested SearchMode. For example, a histogram search could return the number of jobs per employment type (full-time, part-time, and so on) that exist in Mountain View, CA.

Histograms are generally run in parallel with a search call, using the same JobQuery and the same requestMetadata.

The histogram is defined by the histogramQuery field, a single string expression. For details on the functions available for histogram queries, see the histogramQuery documentation.

Retrieving a histogram

The following code sample returns histogram results:

Go

import (
	"context"
	"fmt"
	"io"

	talent "cloud.google.com/go/talent/apiv4beta1"
	"google.golang.org/api/iterator"
	talentpb "google.golang.org/genproto/googleapis/cloud/talent/v4beta1"
)

// histogramSearch searches for jobs with histogram queries.
func histogramSearch(w io.Writer, projectID, companyID string) error {
	ctx := context.Background()

	// Initialize a jobService client.
	c, err := talent.NewJobClient(ctx)
	if err != nil {
		fmt.Printf("talent.NewJobClient: %v\n", err)
		return err
	}

	// Construct a searchJobs request.
	req := &talentpb.SearchJobsRequest{
		Parent: fmt.Sprintf("projects/%s", projectID),
		// Make sure to set the RequestMetadata the same as the associated
		// search request.
		RequestMetadata: &talentpb.RequestMetadata{
			// Make sure to hash your userId.
			UserId: "HashedUsrID",
			// Make sure to hash the sessionId.
			SessionId: "HashedSessionID",
			// Domain of the website where the search is conducted.
			Domain: "www.googlesample.com",
		},
		HistogramQueries: []*talentpb.HistogramQuery{
			{
				// More info on histogram facets, constants, and built-in functions:
				// https://godoc.org/google.golang.org/genproto/googleapis/cloud/talent/v4beta1#SearchJobsRequest
				HistogramQuery: "count(base_compensation, [bucket(12, 20)])",
			},
		},
	}
	if companyID != "" {
		req.JobQuery = &talentpb.JobQuery{
			CompanyNames: []string{fmt.Sprintf("projects/%s/companies/%s", projectID, companyID)},
		}
	}

	it := c.SearchJobs(ctx, req)

	for {
		resp, err := it.Next()
		if err == iterator.Done {
			return nil
		}
		if err != nil {
			fmt.Printf("it.Next: %v\n", err)
			return err
		}
		fmt.Fprintf(w, "Job: %q\n", resp.Job.GetName())
	}
}

Java

For more on installing and creating a Cloud Talent Solution client, see Cloud Talent Solution Client Libraries.


import com.google.cloud.talent.v4.HistogramQuery;
import com.google.cloud.talent.v4.Job;
import com.google.cloud.talent.v4.JobServiceClient;
import com.google.cloud.talent.v4.RequestMetadata;
import com.google.cloud.talent.v4.SearchJobsRequest;
import com.google.cloud.talent.v4.SearchJobsResponse;
import com.google.cloud.talent.v4.TenantName;
import java.io.IOException;

public class HistogramSearchJobs {

  public static void searchJobs() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String tenantId = "your-tenant-id";
    String query = "count(base_compensation, [bucket(12, 20)])";
    searchJobs(projectId, tenantId, query);
  }

  // Search Jobs with histogram queries.
  public static void searchJobs(String projectId, String tenantId, String query)
      throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (JobServiceClient jobServiceClient = JobServiceClient.create()) {
      TenantName parent = TenantName.of(projectId, tenantId);

      String domain = "http://www.jobUrl.com";
      String sessionId = "Hashed session identifier";
      String userId = "Hashed user identifier";
      RequestMetadata requestMetadata =
          RequestMetadata.newBuilder()
              .setDomain(domain)
              .setSessionId(sessionId)
              .setUserId(userId)
              .build();
      HistogramQuery histogramQueriesElement =
          HistogramQuery.newBuilder().setHistogramQuery(query).build();
      SearchJobsRequest request =
          SearchJobsRequest.newBuilder()
              .setParent(parent.toString())
              .setRequestMetadata(requestMetadata)
              .addHistogramQueries(histogramQueriesElement)
              .build();

      for (SearchJobsResponse.MatchingJob responseItem :
          jobServiceClient.searchJobs(request).getMatchingJobsList()) {
        System.out.format("Job summary: %s%n", responseItem.getJobSummary());
        System.out.format("Job title snippet: %s%n", responseItem.getJobTitleSnippet());
        Job job = responseItem.getJob();
        System.out.format("Job name: %s%n", job.getName());
        System.out.format("Job title: %s%n", job.getTitle());
      }
    }
  }
}

Node.js

For more on installing and creating a Cloud Talent Solution client, see Cloud Talent Solution Client Libraries.


const talent = require('@google-cloud/talent').v4;

/**
 * Search Jobs with histogram queries
 *
 * @param query {string} Histogram query
 * More info on histogram facets, constants, and built-in functions:
 * https://godoc.org/google.golang.org/genproto/googleapis/cloud/talent/v4beta1#SearchJobsRequest
 */
function sampleSearchJobs(projectId, tenantId, query) {
  const client = new talent.JobServiceClient();
  // Iterate over all elements.
  // const projectId = 'Your Google Cloud Project ID';
  // const tenantId = 'Your Tenant ID (using tenancy is optional)';
  // const query = 'count(base_compensation, [bucket(12, 20)])';
  const formattedParent = client.tenantPath(projectId, tenantId);
  const domain = 'www.example.com';
  const sessionId = 'Hashed session identifier';
  const userId = 'Hashed user identifier';
  const requestMetadata = {
    domain: domain,
    sessionId: sessionId,
    userId: userId,
  };
  const histogramQueriesElement = {
    histogramQuery: query,
  };
  const histogramQueries = [histogramQueriesElement];
  const request = {
    parent: formattedParent,
    requestMetadata: requestMetadata,
    histogramQueries: histogramQueries,
  };

  client
    .searchJobs(request)
    .then(responses => {
      const resources = responses[0];
      for (const resource of resources.matchingJobs) {
        console.log(`Job summary: ${resource.jobSummary}`);
        console.log(`Job title snippet: ${resource.jobTitleSnippet}`);
        const job = resource.job;
        console.log(`Job name: ${job.name}`);
        console.log(`Job title: ${job.title}`);
      }
    })
    .catch(err => {
      console.error(err);
    });
}

Python

For more on installing and creating a Cloud Talent Solution client, see Cloud Talent Solution Client Libraries.


from google.cloud import talent
import six


def search_jobs(project_id, tenant_id, query):
    """
    Search Jobs with histogram queries

    Args:
      query Histogram query
      More info on histogram facets, constants, and built-in functions:
      https://godoc.org/google.golang.org/genproto/googleapis/cloud/talent/v4beta1#SearchJobsRequest
    """

    client = talent.JobServiceClient()

    # project_id = 'Your Google Cloud Project ID'
    # tenant_id = 'Your Tenant ID (using tenancy is optional)'
    # query = 'count(base_compensation, [bucket(12, 20)])'

    if isinstance(project_id, six.binary_type):
        project_id = project_id.decode("utf-8")
    if isinstance(tenant_id, six.binary_type):
        tenant_id = tenant_id.decode("utf-8")
    if isinstance(query, six.binary_type):
        query = query.decode("utf-8")
    parent = f"projects/{project_id}/tenants/{tenant_id}"
    domain = "www.example.com"
    session_id = "Hashed session identifier"
    user_id = "Hashed user identifier"
    request_metadata = {"domain": domain, "session_id": session_id, "user_id": user_id}
    histogram_queries_element = {"histogram_query": query}
    histogram_queries = [histogram_queries_element]

    # Iterate over all results
    results = []
    request = talent.SearchJobsRequest(
        parent=parent,
        request_metadata=request_metadata,
        histogram_queries=histogram_queries,
    )
    for response_item in client.search_jobs(request=request).matching_jobs:
        print("Job summary: {response_item.job_summary}")
        print("Job title snippet: {response_item.job_title_snippet}")
        job = response_item.job
        results.append(job)
        print("Job name: {job.name}")
        print("Job title: {job.title}")
    return results

Ruby

For more on installing and creating a Cloud Talent Solution client, see Cloud Talent Solution Client Libraries.

require "google/cloud/talent"

# Instantiate a client
job_service = Google::Cloud::Talent.job_service

# project_id = "Your Google Cloud Project ID"
# tenant_id = "Your Tenant ID (using tenancy is required)"
formatted_parent = job_service.tenant_path project: project_id, tenant: tenant_id
domain = "www.example.com"
session_id = "Hashed session identifier"
user_id = "Hashed user identifier"
request_metadata = {
  domain:     domain,
  session_id: session_id,
  user_id:    user_id
}

# query = "count(base_compensation, [bucket(12, 20)])"
histogram_queries_element = { histogram_query: query }
histogram_queries = [histogram_queries_element]

# Iterate over all results.
response = job_service.search_jobs parent:            formatted_parent,
                                   request_metadata:  request_metadata,
                                   histogram_queries: histogram_queries
response.matching_jobs.each do |element|
  puts "Job summary: #{element.job_summary}"
  puts "Job title snippet: #{element.job_title_snippet}"
  job = element.job
  puts "Job name: #{job.name}"
  puts "Job title: #{job.title}"
end

C#

For more on installing and creating a Cloud Talent Solution client, see Cloud Talent Solution Client Libraries.

public static object HistogramSearchJobs(string projectId, string tenantId, string query)
{
    JobServiceClient jobServiceClient = JobServiceClient.Create();
    TenantName name = TenantName.FromProjectTenant(projectId, tenantId);

    string domain = "www.example.com";
    string sessionId = "Hashed session identifier";
    string userId = "Hashed user identifier";
    RequestMetadata requestMetadata = new RequestMetadata
    {
        Domain = domain,
        SessionId = sessionId,
        UserId = userId
    };

    // Examples and formats are explained in the following link:
    // https://cloud.google.com/talent-solution/job-search/docs/reference/rest/v4beta1/projects.tenants.jobs/search#body.request_body.FIELDS.histogram_queries
    HistogramQuery histogramQuery = new HistogramQuery
    {
        HistogramQuery_ = query
    };

    SearchJobsRequest request = new SearchJobsRequest
    {
        ParentAsTenantName = name,
        RequestMetadata = requestMetadata,
    };
    request.HistogramQueries.Add(histogramQuery);

    var response = jobServiceClient.SearchJobs(request);
    foreach (var result in response)
    {
        Console.WriteLine($"Job summary: {result.JobSummary}");
        Console.WriteLine($"Job title snippet: {result.JobTitleSnippet}");
        Job job = result.Job;
        Console.WriteLine($"Job name: {job.Name}");
        Console.WriteLine($"Job title: {job.Title}");
    }

    return 0;
}

Relevance thresholding

Histogram requests do not use relevance thresholding. To ensure that the counts are consistent between a histogram search and an identical job search, disableKeywordMatch in the job search must be false.