@powerhousedao/academy 5.0.0-staging.3 → 5.0.0-staging.30

package/docs/academy/02-MasteryTrack/04-WorkWithData/05-RelationalDbProcessor.md

@@ -1,4 +1,4 @@
-# Relational database processor 
+# Relational database processor
 
 In this chapter, we will implement a **Todo-List** relational database processor. This processor receives processed operations from the reactor and can use the `prevState`, `resultingState`, or data from the operations themselves to populate a database.
 
@@ -18,6 +18,7 @@ ph generate --processor todo-indexer --processor-type relationalDb --document-ty
 ```
 
 **Breaking down this command:**
+
 - `--processor todo-indexer`: Creates a processor with the name "todo-indexer"
 - `--processor-type relationalDb`: Specifies we want a relational database processor (vs other types like analytics or webhook processors)
 - `--document-types powerhouse/todolist`: Tells the processor to only listen for changes to documents of type "powerhouse/todolist"
@@ -25,6 +26,7 @@ ph generate --processor todo-indexer --processor-type relationalDb --document-ty
 This command creates a processor named `todo-indexer` of type `relational database` that listens for changes from documents of type `powerhouse/todolist`.
 
 **What gets generated:**
+
 - A processor class file (`processors/todo-indexer/index.ts`)
 - A database migration file (`processors/todo-indexer/migrations.ts`)
 - A factory file for configuration (`processors/todo-indexer/factory.ts`)
@@ -37,6 +39,7 @@ Next, define your database schema in the `processors/todo-indexer/migration.ts`
 **Understanding Database Migrations**
 
 Migrations are version-controlled database changes that ensure your database schema evolves safely over time. They contain:
+
 - **`up()` function**: Creates or modifies database structures when the processor starts
 - **`down()` function**: Safely removes changes when the processor is removed
 
@@ -47,17 +50,17 @@ The migration file contains `up` and `down` functions that are called when the p
 In the migration.ts file you'll find an example of the todo table default schema:
 
 ```ts
-import { type IRelationalDb } from "document-drive/processors/types"
+import { type IRelationalDb } from "document-drive/processors/types";
 
 export async function up(db: IRelationalDb<any>): Promise<void> {
   // Create table - this runs when the processor starts
   await db.schema
-    .createTable("todo")                           // Creates a new table named "todo"
-    .addColumn("task", "varchar(255)")             // Text column for the task description (max 255 characters)
-    .addColumn("status", "boolean")                // Boolean column for completion status (true/false)
+    .createTable("todo") // Creates a new table named "todo"
+    .addColumn("task", "varchar(255)") // Text column for the task description (max 255 characters)
+    .addColumn("status", "boolean") // Boolean column for completion status (true/false)
     .addPrimaryKeyConstraint("todo_pkey", ["task"]) // Makes "task" the primary key (unique identifier)
-    .ifNotExists()                                 // Only create if table doesn't already exist
-    .execute();                                    // Execute the SQL command
+    .ifNotExists() // Only create if table doesn't already exist
+    .execute(); // Execute the SQL command
 }
 
 export async function down(db: IRelationalDb<any>): Promise<void> {
@@ -67,6 +70,7 @@ export async function down(db: IRelationalDb<any>): Promise<void> {
 ```
 
 **Design Considerations:**
+
 - We're using `task` as the primary key, which means each task description must be unique
 - The `varchar(255)` limit ensures reasonable memory usage
 - The `boolean` status makes it easy to filter completed vs. incomplete tasks
@@ -77,12 +81,13 @@ export async function down(db: IRelationalDb<any>): Promise<void> {
 After defining your database schema, generate TypeScript types for type-safe queries and better IDE support:
 
 ```bash
-ph generate --migration-file processors/todo-indexer/migrations.ts 
+ph generate --migration-file processors/todo-indexer/migrations.ts
 ```
 
 **Why Generate Types?**
 
 TypeScript types provide several benefits:
+
 - **Type Safety**: Catch errors at compile time instead of runtime
 - **IDE Support**: Get autocomplete and IntelliSense for your database queries
 - **Documentation**: Types serve as living documentation of your database structure
@@ -91,6 +96,7 @@ TypeScript types provide several benefits:
 Check your `processors/todo-indexer/schema.ts` file after generation - it will contain the TypeScript types for your database schema.
 
 **Example of generated types:**
+
 ```ts
 // This is what gets auto-generated based on your migration
 export interface Database {
@@ -108,6 +114,7 @@ This give you the opportunity to configure the processor filter in `processors/t
 **Understanding Processor Filters**
 
 Filters determine which document changes your processor will respond to. This is crucial for performance and functionality:
+
 - **Performance**: Only process relevant changes to avoid unnecessary work
 - **Isolation**: Different processors can handle different document types
 - **Scalability**: Distribute processing load across multiple processors
@@ -137,10 +144,10 @@ export const todoIndexerProcessorFactory =
     // Create a filter for the processor
     // This determines which document changes trigger the processor
     const filter: RelationalDbProcessorFilter = {
-      branch: ["main"],                    // Only process changes from the "main" branch
-      documentId: ["*"],                   // Process changes from any document ID (* = wildcard)
+      branch: ["main"], // Only process changes from the "main" branch
+      documentId: ["*"], // Process changes from any document ID (* = wildcard)
       documentType: ["powerhouse/todolist"], // Only process todolist documents
-      scope: ["global"],                   // Process global changes (not user-specific)
+      scope: ["global"], // Process global changes (not user-specific)
     };
 
     // Create the processor instance
@@ -155,8 +162,9 @@ export const todoIndexerProcessorFactory =
 ```
 
 **Filter Options Explained:**
+
 - **`branch`**: Which document branches to monitor (usually "main" for production data)
-- **`documentId`**: Specific document IDs to watch ("*" means all documents)
+- **`documentId`**: Specific document IDs to watch ("\*" means all documents)
 - **`documentType`**: Document types to process (ensures type safety)
 - **`scope`**: Whether to process global changes or user-specific ones
 
@@ -167,12 +175,14 @@ Now implement the actual processor logic in `processors/todo-indexer/index.ts` b
 **Understanding the Processor Lifecycle**
 
 The processor has several key methods:
+
 - **`initAndUpgrade()`**: Runs once when the processor starts (perfect for running migrations)
 - **`onStrands()`**: Runs every time relevant document changes occur (this is where the main logic goes)
 - **`onDisconnect()`**: Cleanup when the processor shuts down
 
 **What are "Strands"?**
 Strands represent a batch of operations that happened to documents. Each strand contains:
+
 - Document ID and metadata
 - Array of operations (create, update, delete, etc.)
 - Previous and resulting document states
@@ -261,6 +271,7 @@ ph generate --subgraph todo
 **What is a Subgraph?**
 
 A subgraph is a GraphQL schema that exposes your processed data to clients. It:
+
 - Provides a standardized API for accessing your relational database data
 - Integrates with the Powerhouse supergraph for unified data access
 - Supports both queries (reading data) and mutations (modifying data)
@@ -275,19 +286,17 @@ import { gql } from "graphql-tag";
 import type { DocumentNode } from "graphql";
 
 export const schema: DocumentNode = gql`
+  # Define the structure of a todo item as returned by GraphQL
+  type ToDoListEntry {
+    task: String! # The task description (! means required/non-null)
+    status: Boolean! # The completion status (true = done, false = pending)
+  }
 
-# Define the structure of a todo item as returned by GraphQL
-type ToDoListEntry {
-  task: String!     # The task description (! means required/non-null)
-  status: Boolean!  # The completion status (true = done, false = pending)
-}
-
-# Define available queries
-type Query {
-  todos(driveId: ID!): [ToDoListEntry]  # Get array of todos for a specific drive
-}
+  # Define available queries
+  type Query {
+    todos(driveId: ID!): [ToDoListEntry] # Get array of todos for a specific drive
+  }
 `;
-
 ```
 
 Open `./subgraphs/todo/resolvers.ts` and configure the resolvers:
@@ -307,18 +316,21 @@ export const getResolvers = (subgraph: Subgraph) => {
       todos: {
         // Resolver function for the "todos" query
         // Arguments: parent object, query arguments, context, GraphQL info
-        resolve: async (_: any, args: {driveId: string}) => {
+        resolve: async (_: any, args: { driveId: string }) => {
           // Query the database using the processor's static query method
           // This gives us access to the namespaced database for the specific drive
-          const todos = await TodoIndexerProcessor.query(args.driveId, relationalDb)
-            .selectFrom("todo")        // Select from the "todo" table
-            .selectAll()              // Get all columns
-            .execute();               // Execute the query
+          const todos = await TodoIndexerProcessor.query(
+            args.driveId,
+            relationalDb,
+          )
+            .selectFrom("todo") // Select from the "todo" table
+            .selectAll() // Get all columns
+            .execute(); // Execute the query
 
           // Transform database results to match GraphQL schema
           return todos.map((todo) => ({
-            task: todo.task,          // Map database "task" column to GraphQL "task" field
-            status: todo.status,      // Map database "status" column to GraphQL "status" field
+            task: todo.task, // Map database "task" column to GraphQL "task" field
+            status: todo.status, // Map database "status" column to GraphQL "status" field
           }));
         },
       },
@@ -327,19 +339,19 @@ export const getResolvers = (subgraph: Subgraph) => {
 };
 ```
 
-
 ## Now query the data via the supergraph.
 
 **Understanding the Supergraph**
 
 The Powerhouse supergraph is a unified GraphQL endpoint that combines:
+
 - **Document Models**: Direct access to your Powerhouse documents
 - **Subgraphs**: Custom data views from your processors
 - **Built-in APIs**: System functionality like authentication and drives
 
 This unified approach means you can query document state AND processed data in a single request, which is perfect for building rich user interfaces.
 
-The Powerhouse supergraph for any given remote drive or reactor can be found under `http://localhost:4001/graphql`. The gateway / supergraph available on `/graphql` combines all the subgraphs, except for the drive subgraph (which is accessible via `/d/:driveId`). To access the endpoint, start the reactor and navigate to the URL with `graphql` appended. The following commands explain how you can test & try the supergraph. 
+The Powerhouse supergraph for any given remote drive or reactor can be found under `http://localhost:4001/graphql`. The gateway / supergraph available on `/graphql` combines all the subgraphs, except for the drive subgraph (which is accessible via `/d/:driveId`). To access the endpoint, start the reactor and navigate to the URL with `graphql` appended. The following commands explain how you can test & try the supergraph.
 
 - Start the reactor:
 
@@ -352,8 +364,9 @@ The Powerhouse supergraph for any given remote drive or reactor can be found und
   ```
   http://localhost:4001/graphql
   ```
-The supergraph allows you to both query & mutate data from the same endpoint. 
-Read more about [subgraphs](/academy/MasteryTrack/WorkWithData/UsingSubgraphs)
+
+  The supergraph allows you to both query & mutate data from the same endpoint.
+  Read more about [subgraphs](/academy/MasteryTrack/WorkWithData/UsingSubgraphs)
 
 <details>
 <summary>**Example: Complete Data Flow from Document Operations to Relational Database**</summary>
@@ -361,6 +374,7 @@ Read more about [subgraphs](/academy/MasteryTrack/WorkWithData/UsingSubgraphs)
 **Understanding the Complete Data Pipeline**
 
 This comprehensive example demonstrates the **entire data flow** in a Powerhouse application:
+
 1. **Storage Layer**: Create a drive (document storage container)
 2. **Document Layer**: Create a todo document and add operations
 3. **Processing Layer**: Watch the relational database processor automatically index changes
@@ -381,7 +395,8 @@ mutation DriveCreation($name: String!) {
 }
 ```
 
-Variables: 
+Variables:
+
 ```json
 {
   "driveId": "powerhouse",
@@ -404,6 +419,7 @@ mutation Mutation($driveId: String, $name: String) {
 ```
 
 Variables:
+
 ```json
 {
   "driveId": "powerhouse",
@@ -412,6 +428,7 @@ Variables:
 ```
 
 Result:
+
 ```json
 {
   "data": {
@@ -429,12 +446,17 @@ Result:
 **What's Happening**: Each time we add a todo item, we're creating a new **operation** in the document's history. Our relational database processor is listening for these operations in real-time.
 
 ```graphql
-mutation Mutation($driveId: String, $docId: PHID, $input: ToDoList_AddTodoItemInput) {
+mutation Mutation(
+  $driveId: String
+  $docId: PHID
+  $input: ToDoList_AddTodoItemInput
+) {
   ToDoList_addTodoItem(driveId: $driveId, docId: $docId, input: $input)
 }
 ```
 
 Variables:
+
 ```json
 {
   "driveId": "powerhouse",
@@ -448,6 +470,7 @@ Variables:
 ```
 
 Result:
+
 ```json
 {
   "data": {
@@ -456,7 +479,8 @@ Result:
 }
 ```
 
-💡 **What Happens Next**: 
+💡 **What Happens Next**:
+
 1. **Document Model**: Stores the operation and updates document state
 2. **Reactor**: Broadcasts the operation to all listening processors
 3. **Our Processor**: Automatically receives the operation and creates a database record
@@ -489,6 +513,7 @@ query Query($driveId: ID!) {
 ```
 
 Variables:
+
 ```json
 {
   "driveId": "powerhouse"
@@ -496,6 +521,7 @@ Variables:
 ```
 
 Response:
+
 ```json
 {
   "data": {
@@ -541,12 +567,14 @@ Response:
 ### **🔍 Data Analysis: Understanding What You're Seeing**
 
 **Document Model Data (`ToDoList.getDocuments`):**
+
 - ✅ **Current State**: Shows the final todo items as they exist in the document
 - ✅ **User-Friendly**: Displays actual todo text like "complete mutation"
 - ✅ **Real-Time**: Always reflects the latest document state
 - ❌ **Limited History**: Doesn't show how the document changed over time
 
 **Processed Relational Data (`todos`):**
+
 - ✅ **Operation History**: Shows each individual operation that occurred
 - ✅ **Audit Trail**: You can see the sequence (0, 1, 2) of operations
 - ✅ **Analytics Ready**: Perfect for counting operations, tracking changes
@@ -556,11 +584,13 @@ Response:
 ---
 
 **Key Differences:**
+
 - **Document Query**: Gets the current state directly from the document model
 - **Subgraph Query**: Gets processed/transformed data from your relational database
 - **Combined Power**: You can query both in a single GraphQL request for rich UIs
 
-This demonstrates how the supergraph provides a unified interface to both your document models and your custom subgraphs, allowing you to query and mutate data from the same endpoint.  
+This demonstrates how the supergraph provides a unified interface to both your document models and your custom subgraphs, allowing you to query and mutate data from the same endpoint.
+
 </details>
 
 ## Use the Data in Frontend Applications
@@ -568,6 +598,7 @@ This demonstrates how the supergraph provides a unified interface to both your d
 **Integration Options**
 
 Your processed data can now be consumed by any GraphQL client:
+
 - **React**: Using Apollo Client, urql, or Relay
 - **Next.js**: API routes, getServerSideProps, or app router
 - **Mobile Apps**: React Native, Flutter, or native iOS/Android
@@ -583,6 +614,7 @@ Your processed data can now be consumed by any GraphQL client:
 **Why API Routes?**
 
 Next.js API routes are useful when you need to:
+
 - Add server-side authentication or authorization
 - Transform data before sending to the client
 - Implement caching or rate limiting
@@ -591,11 +623,11 @@ Next.js API routes are useful when you need to:
 
 ```ts
 // pages/api/todos.ts
-import { type NextApiRequest, type NextApiResponse } from "next"
+import { type NextApiRequest, type NextApiResponse } from "next";
 
 export default async function handler(
   req: NextApiRequest,
-  res: NextApiResponse
+  res: NextApiResponse,
 ) {
   // Only allow GET requests for this endpoint
   if (req.method !== "GET") {
@@ -628,13 +660,13 @@ export default async function handler(
     });
 
     const data = await response.json();
-    
+
     // Return the todos array from the GraphQL response
     res.status(200).json(data.data.todoList);
   } catch (error) {
     // Log the error for debugging (in production, use proper logging)
     console.error("Failed to fetch todos:", error);
-    
+
     // Return a generic error message to the client
     res.status(500).json({ error: "Failed to fetch todos" });
   }
@@ -651,16 +683,14 @@ You've successfully created a relational database processor that:
 4. ✅ **Exposes data through GraphQL** - Makes processed data available via a unified API
 5. ✅ **Can be consumed by frontend applications** - Ready for integration with any GraphQL client
 
-
 This processor will automatically sync your document changes to the relational database, making the data available for complex queries, reporting, and integration with other systems.
 
 **Real-World Applications:**
 
 This pattern is commonly used for:
+
 - **Analytics dashboards** showing document usage patterns
 - **Business intelligence** reports on document data
 - **Integration** with existing enterprise systems
 - **Search and filtering** with complex SQL queries
 - **Data archival** and compliance requirements
-
-

package/docs/academy/02-MasteryTrack/04-WorkWithData/06-Analytics Engine/GraphQL References/QueryingADocumentWithGraphQL.md

@@ -10,10 +10,12 @@ But the **same queries can be used for any other document model**.
 The queries below focus on 2 different ways of receiving the data.
 We will show how you can receive:
 
-> #### 1. The complete state of the document: 
+> #### 1. The complete state of the document:
+>
 > Such as the array of accounts, Special Purpose Vehicles (SPVs), fixed income types, fee types, portfolio details, and transactions associated with a particular RWA-report.
 
 > #### 2. Only the latest changes and updates:
+>
 > Or specific operations of a document by registering a listener with a specific filter.
 
 ### Adding the specific document drive to Connect with a URL
@@ -26,20 +28,20 @@ Get access to an organisations drive instances by adding this drive to your Conn
 
 Whenever you want to start a query from a document within connect you can open up switchboard by looking for the switchboard logo in the top right hand corner of the document editor interface, or by clicking a document in the connect drive explorer and opening the document in switchboard. This feature will not be available for your local drives as they are not hosted on switchboard.
 
-![untitled](./rwa-reports/raw-reports1.png)   
-Right click a document and find a direct link to switchboard GraphQL playground*
+![untitled](./rwa-reports/raw-reports1.png)  
+Right click a document and find a direct link to switchboard GraphQL playground\*
 
 ## Querying data from Connect in Apollo Studio
 
 Aside from switchboard you're able to make use of GraphQL interfaces such as Apollo Studio.
-When opening the document in switchboard the endpoint will be visible at the top of the interface.   Copy this endpoint and use it as your API endpoint in Apollo.
+When opening the document in switchboard the endpoint will be visible at the top of the interface. Copy this endpoint and use it as your API endpoint in Apollo.
 
 ![untitled](./rwa-reports/raw-reports2.png)
-*The endpoint you'll be using for any other GraphQL playgrounds or sandboxes*
+_The endpoint you'll be using for any other GraphQL playgrounds or sandboxes_
 
 ### 1. Querying the complete state of a document
 
-This example query is structured to request a document by its unique identifier (id).   
+This example query is structured to request a document by its unique identifier (id).  
 It extracts common fields such as id, name, documentType, revision, created, and lastModified.
 
 Additionally, it retrieves specific data related to the 'Real World Assets' document model, including accounts, SPVs, fixed income types, fee types, portfolio, and transactions. The RWA section of the query is designed to pull in detailed information about the financial structure and transactions of real-world assets managed within the document model.
@@ -58,6 +60,7 @@ Additionally, it retrieves specific data related to the 'Real World Assets' docu
 #### Real World Assets (RWA) Specific Fields
 
 **State**
+
 - `accounts`
   - `id`: Unique identifier for the account.
   - `reference`: Reference code or number associated with the account.
@@ -94,7 +97,6 @@ Additionally, it retrieves specific data related to the 'Real World Assets' docu
   - `coupon`: Coupon rate of the fixed income asset.
 
   **Cash**
-
   - `id`: Unique identifier for the cash holding.
   - `spvId`: Identifier for the SPV associated with the cash holding.
   - `currency`: Currency of the cash holding
@@ -102,7 +104,7 @@ Additionally, it retrieves specific data related to the 'Real World Assets' docu
 </details>
 
 ```graphql title="An example query for the full state of a document"
-  query {
+query {
   document(id: "") {
     name
     documentType
@@ -158,15 +160,15 @@ Additionally, it retrieves specific data related to the 'Real World Assets' docu
     }
   }
 }
-
 ```
 
 ### 2. Querying for the latest updates or specific documents
 
-This query is particularly useful when you only need the latest changes from the document drive. 
+This query is particularly useful when you only need the latest changes from the document drive.
 
 ### 2.1 Registering a listener
-For this purpose we support adding listeners through a graphQL mutation such as the PullResponderListenerbelow. 
+
+For this purpose we support adding listeners through a graphQL mutation such as the PullResponderListenerbelow.
 
 ```graphql
 mutation registerListener($filter: InputListenerFilter!) {
@@ -178,8 +180,8 @@ mutation registerListener($filter: InputListenerFilter!) {
 
 ### 2.2 Defining the filter
 
-Through this listener you can define the filter with query variables.   
-This allows you to filter for specific document ID's or a lists, documentTypes, scopes or branches.   
+Through this listener you can define the filter with query variables.  
+This allows you to filter for specific document ID's or a lists, documentTypes, scopes or branches.  
 Branches allow you to query different versions of a document in case there is a conflict accross different versions of the document or when contributors are maintaining separate versions with the help of branching
 
     In this case we're filtering by document type makerdao/rwa-portfolio.
@@ -195,20 +197,20 @@ Branches allow you to query different versions of a document in case there is a
 }
 ```
 
-This combination of query + query variables will return a listenerID which can be used in the next step to query for specific strands. 
+This combination of query + query variables will return a listenerID which can be used in the next step to query for specific strands.
 
 ![untitled](./rwa-reports/rwaRegister.png)
-*An example of registering a listener and receiving a listenerId back.*
+_An example of registering a listener and receiving a listenerId back._
 
 :::info
 A strand in this scenario can be understood as a list of operations that has been applied to the RWA portfolio or any other document. As a query variable you'll want to add the received listenerId from the previous step together with the pullstrands query below
 :::
 
-```graphql title="Pullstrands query"	
-query pullStrands ($listenerId:ID, $since: Date) {
+```graphql title="Pullstrands query"
+query pullStrands($listenerId: ID, $since: Date) {
   system {
     sync {
-      strands (listenerId: $listenerId, since: $since) {
+      strands(listenerId: $listenerId, since: $since) {
         driveId
         documentId
         scope
@@ -235,10 +237,10 @@ query pullStrands ($listenerId:ID, $since: Date) {
 ```
 
 ![untitled](./rwa-reports/listener-raw.png)
-*An example of using the ListenerID to pull specific strands (or document operations)* 
+_An example of using the ListenerID to pull specific strands (or document operations)_
 
-In case you'd only like to receive the latest operations of a document the latest timestamp can be used as a filter in the since query variable to only get the most relevant or latest changes. 
+In case you'd only like to receive the latest operations of a document the latest timestamp can be used as a filter in the since query variable to only get the most relevant or latest changes.
 
 :::info
 A "strand" within the context of Powerhouse's Document Synchronization Protocol also refers to a single synchronization channel that connects exactly one unit of synchronization to another, with all four parameters (drive_url, doc_id, scope, branch) set to fixed values. This setup means that synchronization happens at a granular level, focusing specifically on one precise aspect of synchronization between two distinct points of instances of a document or document drive.
-:::
+:::

package/docs/academy/02-MasteryTrack/04-WorkWithData/06-Analytics Engine/best-practices.md

@@ -33,28 +33,28 @@ For example: Looking at the dimension section in the filter options: To see avai
 ### Guidelines for selecting and combining dimensions
 
 1. **Understand the Purpose of Analysis**  
-Before selecting dimensions, clarify the objective of your analysis. Are you looking to track expenses for a specific project, analyze budget utilization, or examine transaction patterns? Your objective will guide which dimensions are most relevant.
+   Before selecting dimensions, clarify the objective of your analysis. Are you looking to track expenses for a specific project, analyze budget utilization, or examine transaction patterns? Your objective will guide which dimensions are most relevant.
 
 2. **Choose Relevant Dimensions**  
-Select dimensions that align with your analytical goals. For instance, use the 'Project' dimension for project-based financial tracking or 'Wallet' for blockchain transaction analysis.
+   Select dimensions that align with your analytical goals. For instance, use the 'Project' dimension for project-based financial tracking or 'Wallet' for blockchain transaction analysis.
 
 3. **Combining Dimensions for Depth**  
-Combine multiple dimensions to gain more nuanced insights. For example, you might combine 'Budget' and 'Category' to understand how different categories of expenses contribute to overall budget utilization within a specific area.
+   Combine multiple dimensions to gain more nuanced insights. For example, you might combine 'Budget' and 'Category' to understand how different categories of expenses contribute to overall budget utilization within a specific area.
 
 4. **Hierarchy and Path Considerations**  
-Pay attention to the hierarchical structure in dimension paths. For instance, paths like atlas/scopes/SUP/I/PHOENIX/ suggest a structured breakdown that can be crucial for detailed analysis.
+   Pay attention to the hierarchical structure in dimension paths. For instance, paths like atlas/scopes/SUP/I/PHOENIX/ suggest a structured breakdown that can be crucial for detailed analysis.
 
 5. **Utilize Descriptions for Context**  
-Where available, use the descriptions provided with dimension values to understand the context and relevance of each dimension to your analysis. This is particularly helpful in dimensions with null labels, where the path and description provide critical information.
+   Where available, use the descriptions provided with dimension values to understand the context and relevance of each dimension to your analysis. This is particularly helpful in dimensions with null labels, where the path and description provide critical information.
 
 6. **Avoid Over-Complication**  
-While combining dimensions can provide depth, avoid overly complex combinations that might lead to confusing or inconclusive results. Stick to combinations that directly serve your analysis objectives.
+   While combining dimensions can provide depth, avoid overly complex combinations that might lead to confusing or inconclusive results. Stick to combinations that directly serve your analysis objectives.
 
 7. **Use Icons for Quick Reference**  
-Where icons are available, they can be used as a quick visual reference to identify different dimensions or categories, particularly in user interfaces where rapid identification is beneficial.
+   Where icons are available, they can be used as a quick visual reference to identify different dimensions or categories, particularly in user interfaces where rapid identification is beneficial.
 
 8. **Experiment and Iterate**  
-Don't hesitate to experiment with different combinations of dimensions to see which provide the most meaningful insights. The flexibility of the dimensions allows for various permutations and combinations to suit diverse analytical needs.
+   Don't hesitate to experiment with different combinations of dimensions to see which provide the most meaningful insights. The flexibility of the dimensions allows for various permutations and combinations to suit diverse analytical needs.
 
 9. **Stay Updated**  
-Keep abreast of any changes or additions to the dimensions within the analytics engine, as this can impact ongoing and future analyses.
+   Keep abreast of any changes or additions to the dimensions within the analytics engine, as this can impact ongoing and future analyses.

package/docs/academy/02-MasteryTrack/04-WorkWithData/06-Analytics Engine/graphql/index.md

@@ -74,7 +74,7 @@ In the provided GraphQL query, each field and element plays a specific role in d
 - `series(filter: $filter)`: This field represents a collection of data points or a data set that matches the criteria specified by the filter. It's an array of results, where each result is a time-bound statistical representation of the filtered data. And passes the `$filter` variable as an argument to determine the scope of the data returned.
 
 - `period`: Within each series, this field denotes the aggregation period for the data (e.g., monthly, quarterly, annually). It's a label describing the time span each series covers.
-start: This is the starting date and time of the data series, indicating when the period begins.
+  start: This is the starting date and time of the data series, indicating when the period begins.
 
 - `end`: This is the ending date and time of the data series, indicating when the period ends.
 
@@ -85,11 +85,11 @@ start: This is the starting date and time of the data series, indicating when th
 - `unit`: This indicates the unit of measurement for the metric, such as quantities, currency (e.g., DAI), or percentages.
 
 - `dimensions`: A nested array that provides context for the metric by breaking it down into finer categories or segments, such as 'project' or 'category'. Each dimension can contain:
-    - `name`: The identifier or key for the dimension.
-    - `path`: A structured representation of the dimension's hierarchy or location within a dataset.
-    - `label`: A human-readable label for the dimension, which can be used for display purposes.
-    - `description`: A brief explanation of the dimension to give users an understanding of what it represents.
-    - `icon`: A graphical representation or icon associated with the dimension for easier identification in user interfaces.
+  - `name`: The identifier or key for the dimension.
+  - `path`: A structured representation of the dimension's hierarchy or location within a dataset.
+  - `label`: A human-readable label for the dimension, which can be used for display purposes.
+  - `description`: A brief explanation of the dimension to give users an understanding of what it represents.
+  - `icon`: A graphical representation or icon associated with the dimension for easier identification in user interfaces.
 
 - `value`: The actual numerical value of the metric for each row within the specified period.
 - `sum`: A total or aggregated value of the metric over the entire period, providing a summarized figure.
@@ -106,7 +106,6 @@ In the analytics engine, the filter object in a GraphQL query is crucial for tai
 
 A filter object must include all the following parameters:
 
-
 1. Start Date (`start`): The beginning date of the data retrieval period.
 
 2. End Date (`end`): The end date of the data retrieval period.
@@ -120,32 +119,21 @@ A filter object must include all the following parameters:
 In the analytics engine, dimensions play a critical role in segmenting and analyzing data. The `select` field within a dimension and its correlation with the level of detail (`lod`)
 parameter are particularly crucial for tailoring your query to retrieve the most relevant and precise data. Here's a detailed explanation of their importance:
 
-The `select` Field in Dimensions
-     - **Function**: The select field specifies the exact segment or category within a dimension that you want to analyze. For example, in a dimension named "project," the select field could specify a particular project like "SES" or "Atlas."
-     - **Path Specification**: The value set in the select field often represents a path in the data hierarchy. This path directs the query to focus on specific segments or nodes within the broader dimension category.
-     - **Precision in Data Retrieval**: By setting the right path in the select field, you ensure that the query fetches data pertinent only to that specific segment, leading to more targeted and relevant insights.
-     - **Example**: If you set the **select** field to "`atlas/scopes/SUP/I/PHOENIX/`" in the "`budget`" dimension, the query will retrieve data related to the budget allocated specifically for the "`PHOENIX`" project under the "`SUP`" scope in the "`Atlas`" system.
+The `select` Field in Dimensions - **Function**: The select field specifies the exact segment or category within a dimension that you want to analyze. For example, in a dimension named "project," the select field could specify a particular project like "SES" or "Atlas." - **Path Specification**: The value set in the select field often represents a path in the data hierarchy. This path directs the query to focus on specific segments or nodes within the broader dimension category. - **Precision in Data Retrieval**: By setting the right path in the select field, you ensure that the query fetches data pertinent only to that specific segment, leading to more targeted and relevant insights. - **Example**: If you set the **select** field to "`atlas/scopes/SUP/I/PHOENIX/`" in the "`budget`" dimension, the query will retrieve data related to the budget allocated specifically for the "`PHOENIX`" project under the "`SUP`" scope in the "`Atlas`" system.
 
-The level of detail (`lod`) Parameter
-    - **Granularity** Within Dimensions: While the select field specifies what to select within a dimension, the `lod` parameter determines how detailed or summarized the information should be.
-    - **Hierarchy Levels**: Different levels in `lod` represent different levels of detail in the data hierarchy. A higher `lod` value typically means a more detailed breakdown, while a lower value indicates a more summarized or aggregated view.
-    - **Correlation with `select` Path**: The lod value you choose should correspond appropriately to the path specified in the `select` field. A mismatch might lead to data that is either too granular or too generalized than what is needed.
-    - **Impact on Analysis**: The level of detail can significantly affect the analysis. For instance, a high lod can provide in-depth insights into a specific area, useful for detailed audits or close examination of a particular segment. Conversely, a low lod is better for broader overviews or when comparing larger categories.
+The level of detail (`lod`) Parameter - **Granularity** Within Dimensions: While the select field specifies what to select within a dimension, the `lod` parameter determines how detailed or summarized the information should be. - **Hierarchy Levels**: Different levels in `lod` represent different levels of detail in the data hierarchy. A higher `lod` value typically means a more detailed breakdown, while a lower value indicates a more summarized or aggregated view. - **Correlation with `select` Path**: The lod value you choose should correspond appropriately to the path specified in the `select` field. A mismatch might lead to data that is either too granular or too generalized than what is needed. - **Impact on Analysis**: The level of detail can significantly affect the analysis. For instance, a high lod can provide in-depth insights into a specific area, useful for detailed audits or close examination of a particular segment. Conversely, a low lod is better for broader overviews or when comparing larger categories.
 
-Importance of Correct Configuration
-    - **Accuracy of Results**: Setting the correct path in the select field and aligning it with an appropriate lod ensures the accuracy and relevance of the query results. Incorrect or mismatched configurations might lead to misleading insights or data that doesn't serve the intended analytical purpose.
-    - **Customized Analysis**: Together, the select field and lod allow for a high degree of customization in data queries. Users can tailor their data requests precisely to their specific requirements, whether they need a broad overview or a detailed breakdown.
-    - Follow the right upper or lower case letter style from metrics, granularity and dimensions.
+Importance of Correct Configuration - **Accuracy of Results**: Setting the correct path in the select field and aligning it with an appropriate lod ensures the accuracy and relevance of the query results. Incorrect or mismatched configurations might lead to misleading insights or data that doesn't serve the intended analytical purpose. - **Customized Analysis**: Together, the select field and lod allow for a high degree of customization in data queries. Users can tailor their data requests precisely to their specific requirements, whether they need a broad overview or a detailed breakdown. - Follow the right upper or lower case letter style from metrics, granularity and dimensions.
 
 6. **Currency (`currency`)**: The currency format for the financial data (e.g., DAI, MKR).
 
 The filter object can be created by using the UI menu from the graphql apollo studio explorer:
 
 ![untitled](../filter.png)
-*Select the filter*
+_Select the filter_
 
 ![untitled](../filteroptions.png)
-*Select all filter fields and sub fields*
+_Select all filter fields and sub fields_
 
 ## Troubleshooting