docs: Extract naming conventions and introduce name parameters in r… (#6484)

* docs: Extract naming conventions and introduce `name` parameters in reference docs

* Update docs/content/Schema/Fundamentals/Syntax.mdx

Co-authored-by: Hassan Khan <[email protected]>

* Update docs/content/Schema/Fundamentals/Syntax.mdx

Co-authored-by: Hassan Khan <[email protected]>

* Update docs/content/Schema/Fundamentals/Syntax.mdx

* Update docs/content/Schema/Fundamentals/Syntax.mdx

---------

Co-authored-by: Hassan Khan <[email protected]>

Author: igorlukanin

docs/content/Schema/Fundamentals/Syntax.mdx

@@ -0,0 +1,91 @@
+---
+title: Syntax
+permalink: /data-modeling/syntax
+category: Data Modeling
+subCategory: Fundamentals
+menuOrder: 12
+redirect_from:
+  - /schema/fundamentals/working-with-yaml
+  - /schema/getting-started/yaml
+---
+
+Entities within the data model (e.g., cubes, views, measures, dimensions, etc.)
+should follow [naming conventions][self-naming] and be defined using a supported
+[syntax][self-syntax].
+
+## Naming
+
+Common rules apply to names of entities within the data model. All names must:
+
+- start with a letter
+- consist of letters, numbers, and underscore (`_`) symbols only
+
+It is also recommended that names use [snake
+case][wiki-snake-case]<!-- and follow the style guide -->.
+
+Good examples of names:
+
+- `orders`, `stripe_invoices`, or `base_payments` (cubes)
+- `opportunities`, `cloud_accounts`, or `arr` (views)
+- `count`, `avg_price`, or `total_amount_shipped` (measures)
+- `name`, `is_shipped`, or `created_at` (dimensions)
+- `main`, `orders_by_status`, or `lambda_invoices` (pre-aggregations)
+
+## Model syntax
+
+Cube supports two ways to define data models: with [YAML][wiki-yaml] or
+JavaScript syntax.
+
+<InfoBox>
+
+YAML syntax is supported since v0.31.0.
+
+</InfoBox>
+
+YAML data models are placed in `.yml` files in the `schema/` folder, whereas
+JavaScript data models are placed in `.js` files in the same folder.
+
+It's recommended to use YAML syntax by default; opt to JavaScript syntax when
+you need to have a
+[dynamic data model](/schema/advanced/dynamic-schema-creation).
+
+<CodeTabs>
+
+```javascript
+cube(`orders`, {
+  sql: `
+    SELECT * FROM
+      orders,
+      line_items
+    WHERE
+      orders.id = line_items.order_id
+  `,
+});
+```
+
+```yaml
+cubes:
+  - name: orders
+    sql: >
+      SELECT * FROM
+        orders,
+        line_items
+      WHERE
+        orders.id = line_items.order_id
+```
+
+</CodeTabs>
+
+### Syntax comparison
+
+YAML syntax is very similar to JavaScript syntax, with a few key differences:
+
+- In YAML syntax, cubes, views, and context variables should be wrapped in `{}`,
+  e.g., `{FILTER_PARAMS.Orders.created_at.filter('created_at')}`.
+- In YAML syntax, string values only need to have quotes around them if they
+  contain special values, e.g., `"{CUBE}.user_id = {Users.id}"`.
+
+[self-naming]: #naming
+[self-syntax]: #code-syntax
+[wiki-snake-case]: https://en.wikipedia.org/wiki/Snake_case
+[wiki-yaml]: https://en.wikipedia.org/wiki/YAML

docs/content/Schema/Fundamentals/Working-with-YAML.mdx

@@ -82,18 +82,6 @@ cubes:
 
 </CodeTabs>
 
-## Naming
-
-There are certain rules to follow for a cube and cube member names:
-
-- Be unique within the project
-- Start with a letter
-- Consist of numbers, letters and `_`
-
-As a convention, cube names start with upper case letters and member names with
-lower case letters. As in JavaScript, [camel case][wiki-camelcase] is used for
-multi-word cube and member names.
-
 ## Members and Referencing
 
 Cubes have three types of members: measures, dimensions and segments. Each
@@ -228,6 +216,28 @@ cube(`Contacts`, {
 
 ## Parameters
 
+### <--{"id" : "Parameters"}--> name
+
+The `name` parameter serves as the identifier of a cube. It must be unique among
+_all cubes and views_ within a deployment and follow the [naming
+conventions][ref-naming].
+
+<CodeTabs>
+
+```javascript
+cube(`orders`, {
+  sql_table: orders,
+});
+```
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: orders
+```
+
+</CodeTabs>
+
 ### <--{"id" : "Parameters"}--> dataSource
 
 Each cube in schema can have its own `dataSource` name to support scenarios
@@ -1043,4 +1053,4 @@ cubes:
 [ref-restapi-meta]: /rest-api#v-1-meta
 [ref-restapi-sql]: /rest-api#v-1-sql
 [ref-sec-ctx]: /security/context
-[wiki-camelcase]: https://en.wikipedia.org/wiki/Camel_case
+[ref-naming]: /data-modeling/syntax#naming

docs/content/Schema/Reference/cube.mdx

@@ -16,19 +16,18 @@ have dimensions like `country`, `age`, `occupation`, etc.
 
 Any dimension should have the following properties: `name`, `sql` and `type`.
 
-## Naming
+## Parameters
 
-You can name a dimension by following the same rules as for measure, so each
-name should:
+### <--{"id" : "Parameters"}--> name
 
-- Be unique within a cube
-- Start with a lowercase letter
-- Consist of numbers, letters and `_`
+The `name` parameter serves as the identifier of a dimension. It must be unique
+among all dimensions, measures, and segments within a cube and follow the
+[naming conventions][ref-naming].
 
 <CodeTabs>
 
 ```javascript
-cube(`Products`, {
+cube(`products`, {
   dimensions: {
     price: {
       sql: `price`,
@@ -45,20 +44,20 @@ cube(`Products`, {
 
 ```yaml
 cubes:
-  - name: Products
+  - name: products
+
     dimensions:
       - name: price
         sql: price
         type: number
+
       - name: brand_name
         sql: brand_name
         type: string
 ```
 
 </CodeTabs>
 
-## Parameters
-
 ### <--{"id" : "Parameters"}--> case
 
 The `case` statement is used to define if/then/else conditions to display data.
@@ -399,3 +398,4 @@ cubes:
   /schema/reference/types-and-formats#dimensions-types
 [ref-subquery]: /schema/fundamentals/additional-concepts#subquery
 [self-subquery]: #sub-query
+[ref-naming]: /data-modeling/syntax#naming

docs/content/Schema/Reference/dimensions.mdx

@@ -61,38 +61,40 @@ parameter. Quite frequently, `FULL OUTER JOIN` is used to solve [Data
 Blending][ref-schema-data-blenging] or similar problems. In that case, it's best
 practice to have a separate cube for such an operation.
 
-## Naming
+## Parameters
+
+### <--{"id" : "Parameters"}--> name
 
-The name of a join should match the [name of the external
-cube][ref-schema-cube-naming]. For example when a `Products` cube is being
-joined on to an `Orders` cube, we would define the join as follows:
+The name must match the name of the joined cube and, thus, follow the [naming
+conventions][ref-naming].
+
+For example, when the `products` cube is joined on to the `orders` cube, we
+would define the join as follows:
 
 <CodeTabs>
 
 ```javascript
-cube('Orders', {
+cube(`orders`, {
   joins: {
-    Products: {
+    products: {
       relationship: `belongsTo`,
-      sql: `${CUBE.id} = ${Products.orderId}`,
+      sql: `${CUBE.id} = ${products.order_id}`,
     },
   },
 });
 ```
 
 ```yaml
 cubes:
-  - name: Orders
+  - name: orders
     joins:
-      - name: Products
+      - name: products
         relationship: belongs_to
-        sql: "{CUBE.id} = {Products.order_id}"
+        sql: '{CUBE.id} = {products.order_id}'
 ```
 
 </CodeTabs>
 
-## Parameters
-
 ### <--{"id" : "Parameters"}--> relationship
 
 `relationship` enables you to describe the join relationship between joined
@@ -471,9 +473,9 @@ algorithm][wiki-djikstra-alg] to find join path between cubes given requested
 members.
 
 [ref-restapi-query-filter-op-set]: /query-format#set
-[ref-schema-cube-naming]: /schema/reference/cube#naming
 [ref-schema-fundamentals-join-dir]:
   /schema/fundamentals/joins#directions-of-joins
 [ref-schema-cube-sql]: /schema/reference/cube#parameters-sql
 [ref-schema-data-blenging]: /schema/advanced/data-blending#data-blending
+[ref-naming]: /data-modeling/syntax#naming
 [wiki-djikstra-alg]: https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm

docs/content/Schema/Reference/joins.mdx

@@ -15,19 +15,18 @@ aggregation over a certain column in your database table.
 
 Any measure should have the following properties: `name`, `sql` and `type`.
 
-## Naming
+## Parameters
 
-When you give a name to a measure, there are certain rules to follow. Each
-measure should:
+### <--{"id" : "Parameters"}--> name
 
-- Be unique within a cube
-- Start with a lowercase letter
-- Consist of numbers, letters and `_`
+The `name` parameter serves as the identifier of a measure. It must be unique
+among all measures, dimensions, and segments within a cube and follow the
+[naming conventions][ref-naming].
 
 <CodeTabs>
 
 ```javascript
-cube(`Orders`, {
+cube(`orders`, {
   measures: {
     count: {
       sql: `id`,
@@ -44,20 +43,20 @@ cube(`Orders`, {
 
 ```yaml
 cubes:
-  - name: Orders
+  - name: orders
+
     measures:
       - name: count
         sql: id
         type: count
+
       - name: total_amount
         sql: amount
         type: sum
 ```
 
 </CodeTabs>
 
-## Parameters
-
 ### <--{"id" : "Parameters"}--> description
 
 You can add details to a measure’s definition via the `description` parameter:
@@ -459,7 +458,7 @@ cubes:
   - name: Orders
     measures:
       - name: purchases_to_created_account_ratio
-        sql: "{purchases} / {Users.count} * 100.0"
+        sql: '{purchases} / {Users.count} * 100.0'
         type: number
         format: percent
 ```
@@ -474,3 +473,4 @@ join will be created automatically.
 [ref-schema-ref-types-formats-measures-formats]:
   /schema/reference/types-and-formats#measures-formats
 [ref-drilldowns]: /schema/fundamentals/additional-concepts#drilldowns
+[ref-naming]: /data-modeling/syntax#naming