Juicebox — Advanced Analysis

Overview

Build custom queries, apply multi-dimensional filters, and run cross-dataset analysis on your Juicebox people-intelligence data. Use this workflow when you need to go beyond standard search — comparing candidate pools across roles, analyzing skill density by geography, or identifying talent trends over time. This is the secondary workflow; for basic search and enrichment, see juicebox-core-workflow-a.

Instructions

Step 1: Build a Custom Query with Filters

const query = await client.analysis.query({
  dataset: 'candidates',
  filters: [
    { field: 'skills', operator: 'contains_any', value: ['TypeScript', 'Rust', 'Go'] },
    { field: 'experience_years', operator: 'gte', value: 5 },
    { field: 'location.country', operator: 'eq', value: 'US' },
  ],
  sort: { field: 'relevance_score', order: 'desc' },
  limit: 100,
});
console.log(`Found ${query.total} candidates matching filters`);
query.results.forEach(c =>
  console.log(`  ${c.name} — ${c.title} (${c.relevance_score}/100)`)
);

Step 2: Run Cross-Dataset Comparison

const comparison = await client.analysis.compare({
  datasets: ['candidates_q1_2026', 'candidates_q4_2025'],
  group_by: 'primary_skill',
  metrics: ['count', 'avg_experience', 'avg_salary_estimate'],
});
comparison.groups.forEach(g =>
  console.log(`${g.skill}: Q1=${g.datasets[0].count} vs Q4=${g.datasets[1].count} (${g.delta > 0 ? '+' : ''}${g.delta}%)`)
);

Step 3: Aggregate Skill Density by Region

const density = await client.analysis.aggregate({
  dataset: 'candidates',
  group_by: 'location.metro_area',
  metric: 'skill_density',
  skill_filter: ['ML Engineering', 'Data Science'],
  top_n: 10,
});
density.regions.forEach(r =>
  console.log(`${r.metro}: ${r.candidate_count} candidates, density=${r.density_score}`)
);

Step 4: Export Analysis Results

const exportJob = await client.analysis.export({
  query_id: query.id,
  format: 'csv',
  fields: ['name', 'email', 'primary_skill', 'experience_years', 'location'],
});
console.log(`Export ready: ${exportJob.download_url} (${exportJob.row_count} rows)`);

Error Handling

Issue	Cause	Fix
400 Invalid filter	Unsupported operator for field type	Check field schema with client.schema.fields()
404 Dataset not found	Stale dataset ID or typo	List datasets with client.datasets.list()
408 Query timeout	Too many filters on large dataset	Add limit or narrow date range
429 Rate limited	Exceeded analysis quota	Implement backoff; check plan limits
Partial comparison data	One dataset has sparse coverage	Expected — use include_nulls: true for completeness

Output

A successful workflow produces filtered candidate lists with relevance scores, cross-dataset comparison tables showing talent market shifts, and regional skill-density rankings. Results can be exported as CSV for downstream reporting.

Prerequisites

• An approved analysis purpose, sandbox datasets containing only synthetic records, source/destination allowlists, a suppression check, and a named owner for review and rollback.

Examples

Run the comparison in workspace=ci-synthetic, restrict output to aggregate metrics, verify suppression=pass; contacts_exported=0, then delete the staged dataset after the redacted receipt is approved.

Resources

• Juicebox API Docs

Next Steps

See juicebox-sdk-patterns for authentication and query builder helpers.