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.

juicebox-core-workflow-b