Overview
The UDE makes all platform data queryable through a unified interface. It powers filtering, reporting, segmentation, and AI agent access across the entire platform.
Find entities matching criteria with powerful filter operators and nested conditions.
Add fields from any source to lists and exports - user data, devices, resources, insights.
Embed live data in content and emails using {{field.path}} syntax.
Query Contexts
Every query operates in one of three contexts
| Context | Root Entity | Available At | Use Cases |
|---|---|---|---|
| user | Users enriched with all their data | Program, Project | Segmentation, participant lists, audience targeting |
| insight | Insights enriched with submitter | Project | Triage, reporting, prioritization |
| project | Projects enriched with aggregates | Program | Program dashboard, cross-project comparison |
Context determines the root entity. All other data is accessed as enrichment: insight.submitter.devices[].product.name queries insights but accesses submitter device data.
Scope Hierarchy
Data flows DOWN the hierarchy
- user.* (account, profile)
- user.devices[].*
- Aggregates across ALL programs
- user.* (inherited)
- program.* (program stats)
- resources.* (program resources)
- user.*, program.* (inherited)
- project.* (project stats)
- insights.* (project insights)
Scope-relative aggregations: user.insightCount at project scope means insights in THIS project. At program scope, it means insights across ALL projects in the program.
Field Sources
| Source | Path Pattern | Examples |
|---|---|---|
| ACCOUNT | user.* | user.name, user.email |
| DEVICE | user.devices[].* | user.devices[].product.brand |
| BLOCK | resources.{slug}.blocks.{id} | resources.nda.blocks.signature |
| RESOURCE_META | resources.{slug}.* | resources.nda.completed, completedAt |
| INSIGHT_META | insight.* | insight.impactScore, insight.status |
| USER_META | user.* (computed) | user.insightCount, user.deviceCount |
Query Example
User Query with Device Filter
Complex filtering with nested conditions
// UDE Query - Find users who completed NDA and have Apple devices
const query: UDEQuery = {
context: 'user',
scope: { projectId: 'proj_123' },
filters: {
operator: 'AND',
conditions: [
{ field: 'resources.nda_survey.completed', operator: 'is_true' },
{
field: 'user.devices',
operator: 'any',
value: { field: 'product.brand', operator: 'eq', value: 'Apple' },
},
],
},
columns: ['user.name', 'user.email', 'resources.nda_survey.completedAt'],
sort: { field: 'user.name', direction: 'asc' },
limit: 50,
};Filter Operators
Operators available by field type
// Filter Operators by Field Type
// Boolean
{ field: 'resources.nda.completed', operator: 'is_true' }
// Text
{ field: 'user.name', operator: 'contains', value: 'John' }
// Number
{ field: 'user.insightCount', operator: 'gte', value: 5 }
// Date
{ field: 'resources.nda.completedAt', operator: 'within_last', value: { count: 7, unit: 'days' } }
// Select
{ field: 'insight.status', operator: 'is_any_of', value: ['open', 'in_progress'] }
// Array (devices, tags)
{ field: 'user.devices', operator: 'any', value: { field: 'product.brand', operator: 'eq', value: 'Apple' } }Token Resolution
Personalized Content
Embed live data in templates
// Token Resolution - Personalize content with live data
const template = `
Hello {{user.name}},
Your device: {{user.devices[0].product.name}}
Completed NDA: {{resources.nda_survey.completedAt}}
`;
const resolved = await resolveTokens(template, {
userId: 'user_123',
projectId: 'proj_123',
});
// "Hello John Doe, Your device: iPhone 17 Pro, Completed NDA: 2024-01-15"AI Direction Tips
When directing AI agents to work with UDE:
- Reference context: 'Query in user context' or 'Use insight context for triage'
- Specify field paths: 'Filter by resources.nda.completed' or 'Include user.devices[].product.brand'
- Mention operators: 'Use any operator to match any device with brand Apple'
- For tokens: 'Resolve {{user.name}} in the email template'
- Reference the ude skill: 'Load ude/QUERIES.md for filter patterns'