analytics_query

Execute an analytics query against the semantic layer. Supports measures, dimensions, filters, and time dimensions.

---

Description

The primary tool for running analytics queries. Returns data from the semantic layer with support for aggregations, grouping, filtering, and time-based analysis.

---

Input Schema

{
  "type": "object",
  "properties": {
    "measures": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Array of measure names (e.g., ['Studies.count', 'Enrollments.count'])"
    },
    "dimensions": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Array of dimension names (e.g., ['Studies.studyName', 'Sites.siteName'])"
    },
    "filters": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "member": { "type": "string" },
          "operator": { "type": "string" },
          "values": { "type": "array", "items": { "type": "string" } }
        }
      },
      "description": "Array of filter objects"
    },
    "timeDimensions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "dimension": { "type": "string" },
          "granularity": { "type": "string" },
          "dateRange": { "type": "array", "items": { "type": "string" } }
        }
      },
      "description": "Time dimension settings for date-based queries"
    },
    "limit": {
      "type": "number",
      "description": "Maximum number of rows to return (default: 100)"
    },
    "order": {
      "type": "object",
      "description": "Sort order as { 'Measure.name': 'asc' | 'desc' }"
    }
  },
  "required": []
}

Parameters

Parameter	Type	Required	Description
measures	array	No	Metrics to aggregate (e.g., counts, sums)
dimensions	array	No	Fields to group by
filters	array	No	Conditions to filter data
timeDimensions	array	No	Time-based grouping and filtering
limit	number	No	Max rows (default: 100)
order	object	No	Sort order

Filter Operators

Operator	Description	Example
equals	Exact match	{"member": "Studies.status", "operator": "equals", "values": ["Active"]}
notEquals	Not equal	{"member": "Studies.phase", "operator": "notEquals", "values": ["Phase 1"]}
contains	String contains	{"member": "Studies.studyName", "operator": "contains", "values": ["COVID"]}
gt / gte	Greater than	{"member": "Subjects.count", "operator": "gt", "values": ["100"]}
lt / lte	Less than	{"member": "AdverseEvents.severity", "operator": "lte", "values": ["3"]}
inDateRange	Date range	{"member": "Studies.startDate", "operator": "inDateRange", "values": ["2024-01-01", "2024-12-31"]}

Time Granularities

Granularity	Description
day	Group by day
week	Group by week
month	Group by month
quarter	Group by quarter
year	Group by year

---

Examples

Simple Count

Request: "How many studies do we have?"

{
  "measures": ["Studies.count"]
}

Response:

{
  "data": [
    { "Studies.count": 42 }
  ]
}

Grouped Query

Request: "Show enrollment counts by study"

{
  "measures": ["Enrollments.count"],
  "dimensions": ["Studies.studyName"]
}

Response:

{
  "data": [
    { "Studies.studyName": "TRIAL-001", "Enrollments.count": 156 },
    { "Studies.studyName": "TRIAL-002", "Enrollments.count": 89 },
    { "Studies.studyName": "TRIAL-003", "Enrollments.count": 234 }
  ]
}

Filtered Query

Request: "Count serious adverse events"

{
  "measures": ["AdverseEvents.count"],
  "filters": [
    {
      "member": "AdverseEvents.serious",
      "operator": "equals",
      "values": ["Yes"]
    }
  ]
}

Time Series Query

Request: "Show monthly enrollment trends for 2024"

{
  "measures": ["Enrollments.count"],
  "timeDimensions": [
    {
      "dimension": "Enrollments.enrollmentDate",
      "granularity": "month",
      "dateRange": ["2024-01-01", "2024-12-31"]
    }
  ]
}

Response:

{
  "data": [
    { "Enrollments.enrollmentDate.month": "2024-01-01T00:00:00.000", "Enrollments.count": 45 },
    { "Enrollments.enrollmentDate.month": "2024-02-01T00:00:00.000", "Enrollments.count": 52 },
    { "Enrollments.enrollmentDate.month": "2024-03-01T00:00:00.000", "Enrollments.count": 61 }
  ]
}

Sorted with Limit

Request: "Top 5 sites by subject count"

{
  "measures": ["Subjects.count"],
  "dimensions": ["Sites.siteName"],
  "order": { "Subjects.count": "desc" },
  "limit": 5
}

---

Complex Query Example

Request: "Show Phase 3 study enrollments by site for 2024, sorted by count"

{
  "measures": ["Enrollments.count"],
  "dimensions": ["Studies.studyName", "Sites.siteName"],
  "filters": [
    {
      "member": "Studies.phase",
      "operator": "equals",
      "values": ["Phase 3"]
    }
  ],
  "timeDimensions": [
    {
      "dimension": "Enrollments.enrollmentDate",
      "dateRange": ["2024-01-01", "2024-12-31"]
    }
  ],
  "order": { "Enrollments.count": "desc" },
  "limit": 20
}

---

Natural Language Examples

You Ask	Query Built
"How many subjects enrolled?"	measures: ["Subjects.count"]
"Enrollments by study"	measures: ["Enrollments.count"], dimensions: ["Studies.studyName"]
"Active studies only"	filters: [{"member": "Studies.status", "operator": "equals", "values": ["Active"]}]
"Monthly trends"	timeDimensions: [{..., "granularity": "month"}]
"Top 10 sites"	order: {...: "desc"}, limit: 10

---

Error Handling

Invalid Measure/Dimension

{
  "error": "Measure 'Studies.invalidMeasure' not found"
}

Empty Result

{
  "data": [],
  "annotation": {
    "measures": ["Studies.count"],
    "dimensions": [],
    "filters": [...]
  }
}