diff --git a/content/docs/api/client-sdk.mdx b/content/docs/api/client-sdk.mdx
index 4116b19622..4bdaaf52f7 100644
--- a/content/docs/api/client-sdk.mdx
+++ b/content/docs/api/client-sdk.mdx
@@ -264,7 +264,7 @@ for the underlying endpoint contract.
 // Semantic analytics query (cube-style)
 const result = await client.analytics.query({
   cube: 'account',
-  measures: ['revenue.sum', 'count'],
+  measures: ['revenue_sum', 'count'],
   dimensions: ['industry'],
   where: { status: 'active' },
   limit: 100,
@@ -276,7 +276,7 @@ const meta = await client.analytics.meta('account');
 // Dry-run a query to its generated SQL (POST /analytics/sql)
 const explained = await client.analytics.explain({
   cube: 'account',
-  measures: ['revenue.sum'],
+  measures: ['revenue_sum'],
 });
 ```
 
diff --git a/content/docs/api/data-api.mdx b/content/docs/api/data-api.mdx
index 86c56acf01..2c3870466e 100644
--- a/content/docs/api/data-api.mdx
+++ b/content/docs/api/data-api.mdx
@@ -335,13 +335,28 @@ Execute an analytics query.
 ```json
 {
   "cube": "account",
-  "measures": ["revenue.sum", "count"],
+  "measures": ["revenue_sum", "count"],
   "dimensions": ["industry"],
   "where": { "status": "active" },
   "limit": 100
 }
 ```
 
+<Callout type="info">
+**How to spell a measure.** A `measures` entry is either a measure the Cube **declares**,
+or one of the inferred spellings: the bare `count` (`COUNT(*)`), or one of the object's
+**own** field names plus an aggregation suffix — `_sum`, `_avg`, `_min`, `_max`,
+`_count_distinct`. So "the sum of `revenue`" is `revenue_sum`.
+
+A dot is legal **only** as the `<cube>.` qualifier: `account.revenue_sum` resolves to the
+same measure as `revenue_sum` (the response column keeps whichever of the two you sent).
+Any other dotted spelling — `revenue.sum`, `owner.amount_sum` — is refused with
+`400 INVALID_FIELD` naming the spelling you sent, and nothing is executed: measures do not
+traverse relationships, only dimensions do, so there is no related column for a dotted
+measure to aggregate. To aggregate a related column, declare a Cube whose measure names it
+in its own `sql`.
+</Callout>
+
 <Callout type="info">
 Filtering uses the canonical Query DSL `where` object (the same MongoDB-style `FilterCondition` accepted by `find()`), not a `filters` array.
 </Callout>
@@ -352,12 +367,12 @@ Filtering uses the canonical Query DSL `where` object (the same MongoDB-style `F
   "success": true,
   "data": {
     "rows": [
-      { "industry": "Technology", "revenue.sum": 150000, "count": 5 },
-      { "industry": "Healthcare", "revenue.sum": 80000, "count": 3 }
+      { "industry": "Technology", "revenue_sum": 150000, "count": 5 },
+      { "industry": "Healthcare", "revenue_sum": 80000, "count": 3 }
     ],
     "fields": [
       { "name": "industry", "type": "string", "label": "Industry" },
-      { "name": "revenue.sum", "type": "number", "label": "Revenue Sum", "format": "$0,0" },
+      { "name": "revenue_sum", "type": "number", "label": "Revenue Sum", "format": "$0,0" },
       { "name": "count", "type": "number", "label": "Count" }
     ],
     "sql": "SELECT ..."