Data is provided to Studio using the data property.
Data is retrieved from data sources. A data source represents one or more tables of data.
When multiple tables are provided, Relationships describe how the tables are linked.
There are two main types of data source:
- Sync Data for data which has already been loaded in the application.
- Async Data for data which is lazy loaded on demand.
See Sharing & Caching Data to reuse one data source across multiple instances of Studio.
The example above demonstrates configuring a single Sync Data.
const data = useMemo(() => {
return {
sources: [{
id: 'medals',
data: [
{
year: 2000,
sport: 'Swimming',
country: 'United States',
// ... other fields
},
// ... other rows
],
}],
};
}, []);
<AgStudio data={data} /> Relationships Copy Link
When multiple tables are provided, if there are relationships between the data, then these should be provided alongside the data sources. This will allow fields from different tables to be displayed together in the same widget.
The example above demonstrates two tables, Medals and Capitals, linked together by country. Both tables are Sync Data.
const data = useMemo(() => {
return {
sources: [{
id: 'medals',
data: [
{
year: 2000,
sport: 'Swimming',
country: 'United States',
// ... other fields
},
// ... other rows
],
}, {
id: 'capitals',
data: [
{
country: 'United States',
capital: 'Washington DC',
// ... other fields
},
// ... other rows
],
}],
relationships: [
{
id: 'medals-capitals',
source: {
tableId: 'medals',
fieldId: 'country',
},
target: {
tableId: 'capitals',
fieldId: 'country',
},
type: 'many-to-one'
},
],
};
}, []);
<AgStudio data={data} />Normal relationships are defined using the AgDataRelationDefinition interface:
ID of the relationship. |
Source field. |
Target field. |
The cardinality of the relationship from the source field to the target field. |
Joining Dates Copy Link
By default date fields are joined the same way as any other field, where matching rows are linked by exact date value.
It is also possible to join date fields of different granularities, or to override the granularity at which they are joined.
This is done by using a ::unit field ID in the relationship, Studio derives a bucketed column from the base date field and uses it as the join key.
The following units are supported. The value column shows the integer each unit produces, which is what the join key is compared against.
| Unit | Value | Example |
|---|---|---|
year | Calendar year | 2024 |
quarter | 1-4 | 1 = Jan-Mar |
month | 1-12 | 1 = January |
monthOfQuarter | 1-3 | Position within the quarter |
week | 1-53 | ISO 8601 week number |
weekOfMonth | 1-5 | floor((day − 1) / 7) + 1 |
day / dayOfMonth | 1-31 | Day of the month |
dayOfWeek | 1-7 | 1 = Monday, 7 = Sunday (ISO 8601) |
weekend | 0 or 1 | 0 = weekday, 1 = weekend |
hour | 0-23 | UTC hour |
timeOfDay | 0-3 | floor(hour / 6) - 0 = Night, 1 = Morning, 2 = Afternoon, 3 = Evening |
minute | 0-59 | UTC minute |
second | 0-59 | UTC second |
Both sides of the relationship can use ::unit. When they do, both must declare the same unit. Using different units on each side is a configuration error.
A plain date column can also appear on one side without a ::unit suffix. Studio extracts the same unit from it automatically, so both keys are comparable integers.
// Valid: both sides extract the same unit
{
id: 'orders-targets',
source: { tableId: 'orders', fieldId: 'order_date::quarter' },
target: { tableId: 'targets', fieldId: 'target_date::quarter' },
type: 'many-to-one',
}
// Valid: one side declares the common unit; the plain date side inherits it
{
id: 'orders-targets',
source: { tableId: 'orders', fieldId: 'order_date' },
target: { tableId: 'targets', fieldId: 'target_date::quarter' },
type: 'many-to-one',
}
// Error: mismatched units
{
id: 'orders-targets',
source: { tableId: 'orders', fieldId: 'order_date::month' },
target: { tableId: 'targets', fieldId: 'target_date::year' },
type: 'many-to-one',
}The example above demonstrates joining at different granularities.
Data API Copy Link
Properties available on the AgDataSourcesDefinition<TRegistry extends AgBaseRegistry = AgDefaultRegistry> interface.
One or more data sources. |
When using multiple related tables, this describes the fields that link the tables together. |
Expression field definitions for calculated columns. |
Overrides to existing formats, or additional custom formats. |
AI-facing overview of the entire dataset: what it contains, what it's for, domain quirks. |
Named time dimensions (calendars) that supply date fragments and a continuous date spine. |
Additional date-fragment bucket definitions to register alongside the built-in set (year, quarter, month, week, day, monthOfYear, dayOfWeek, …). Use this to add project-specific groupings such as weekend, dayOfMonth, or hour that the built-in registry does not include. Provide via createBuckets so type-level registry inference works correctly.
|