diff --git a/docs/architecture.mdx b/docs/architecture.mdx
index 7b8f8c2e..36f42d04 100644
--- a/docs/architecture.mdx
+++ b/docs/architecture.mdx
@@ -71,4 +71,4 @@ performance through the distributed execution layer.
## Next steps
With a broad perspective of the different services powering a PromptQL application, we recommend learning more about the
-[semantic metadata layer](/data-modeling/index.mdx) next.
+[semantic metadata layer](/metadata/index.mdx) next.
diff --git a/docs/business-logic/dev-mode.mdx b/docs/business-logic/dev-mode.mdx
index 1d86c133..6b3147e6 100644
--- a/docs/business-logic/dev-mode.mdx
+++ b/docs/business-logic/dev-mode.mdx
@@ -29,7 +29,7 @@ If you're adding new functions that will need to be exposed as [commands](/refer
your application, or modifying existing functions' arguments or return types, you'll still need to regenerate your
metadata and create a new build of your application.
-Follow the steps [here](/data-modeling/iterate.mdx) for more information.
+Follow the steps [here](/metadata/guides/iterate.mdx) for more information.
:::
diff --git a/docs/capabilities.mdx b/docs/capabilities.mdx
index 0eae8012..0bc75ad0 100644
--- a/docs/capabilities.mdx
+++ b/docs/capabilities.mdx
@@ -40,7 +40,7 @@ means something specific in your business, or that certain metrics should always
:::info Learn more
-You can learn more about PromptQL's semantic understanding [here](/data-modeling/index.mdx).
+You can learn more about PromptQL's semantic understanding [here](/metadata/index.mdx).
:::
diff --git a/docs/data-modeling/_category_.json b/docs/data-modeling/_category_.json
deleted file mode 100644
index 0c70b25a..00000000
--- a/docs/data-modeling/_category_.json
+++ /dev/null
@@ -1,8 +0,0 @@
-{
- "label": "Data Modeling",
- "position": 4,
- "className": "data-modeling",
- "customProps": {
- "sidebar_pathname": "data-modeling"
- }
-}
diff --git a/docs/data-modeling/command.mdx b/docs/data-modeling/command.mdx
deleted file mode 100644
index e8e88343..00000000
--- a/docs/data-modeling/command.mdx
+++ /dev/null
@@ -1,135 +0,0 @@
----
-sidebar_position: 4
-sidebar_label: "Commands act on data"
-description: "Commands allow PromptQL to act on your data in various data sources."
-toc_max_heading_level: 4
-keywords:
- - command
- - data modeling
- - promptql
----
-
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-import Thumbnail from "@site/src/components/Thumbnail";
-
-import CommandCreateLambdaGoNativeOperationHowTo from "@site/docs/data-modeling/partials/lambda-connectors/go/_command-create-native-operation-how-to.mdx";
-import CommandCreateLambdaPythonNativeOperationHowTo from "@site/docs/data-modeling/partials/lambda-connectors/python/_command-create-native-operation-how-to.mdx";
-import CommandCreateLambdaTypescriptNativeOperationHowTo from "@site/docs/data-modeling/partials/lambda-connectors/typescript/_command-create-native-operation-how-to.mdx";
-import CommandCreatePostgreSQLNativeOperationHowTo from "@site/docs/data-modeling/partials/classic-connectors/postgreSQL/_command-create-native-operation-how-to.mdx";
-
-# Commands Enable PromptQL to Modify Data
-
-## Introduction
-
-Commands are a crucial component that enable PromptQL to take action on your data. While PromptQL can intelligently
-query your data through natural language conversations, commands allow it to go further by modifying data (inserts,
-updates, deletes), executing complex operations, or implementing custom business logic across your connected data
-sources.
-
-When a user requests changes to their data through PromptQL, the system dynamically builds a query plan that
-incorporates these commands as part of its execution strategy, providing high accuracy and detailed explanations of each
-action taken.
-
-## Lifecycle
-
-When setting up commands for use with PromptQL, follow this lifecycle:
-
-1. Have some operation in your data source that you want to make executable via PromptQL.
-2. Introspect your data source using the CLI with the relevant data connector to fetch the operation resources.
-3. Add the command to your metadata with the CLI.
-4. Create a build with the CLI.
-5. Serve your build via the packaged distributed query engine, either locally or in the cloud.
-6. Interact with your data through PromptQL, which can now execute these commands as part of its dynamic query planning.
-
-
-
-## Create a command
-
-To add a command you will need to have a data connector already set up and connected to the data source. Follow the
-[Quickstart](/quickstart.mdx) or the tutorial in [How to Build with DDN](/how-to-build-with-promptql/index.mdx) to get
-to that point.
-
-### From a source operation
-
-Some data connectors support the ability to introspect your data source to discover the commands that can be added to
-your metadata layer automatically.
-
-```ddn title="Introspect your data source:"
-ddn connector introspect
-```
-
-```ddn title="Show the resources discovered from your data source:"
-ddn connector show-resources
-```
-
-```ddn title="Add the command from the discovered resources to your metadata:"
-ddn command add
-```
-
-Or you can optionally add all the commands by specifying `"*"`.
-
-```ddn title="Add all commands from your data source:"
-ddn command add "*"
-```
-
-This will add commands with their accompanying metadata definitions to your metadata.
-
-### Via native operations {#via-native-operations-how-to}
-
-Some data connectors support the ability to add commands via native operations so that you can add any operation that is
-not supported by the automatic introspection process.
-
-For classic database connectors, this will be native query code for that source. This can be, for example, a more
-complex read operation or a way to run custom business logic, which PromptQL can incorporate into its query plan.
-
-For Lambda connectors, eg: (TypeScript, Go, Python, etc) this will be a function (read-only) or procedure (mutation or
-other side-effects) that PromptQL can use to execute specialized operations on your data.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Once set up, PromptQL will automatically consider these commands when generating query plans based on user requests,
-enabling accurate data modifications and complex operations through natural language interactions.
-
-## Update a command
-
-When your underlying data source changes, you'll need to update the commands available to PromptQL to ensure continued
-accuracy in its operations:
-
-```ddn title="Introspect your data source:"
-ddn connector introspect
-```
-
-```ddn title="Then, update your existing command:"
-ddn command update
-```
-
-You will see an output which explains how new resources were added or updated in the command.
-
-After updating, PromptQL will automatically incorporate these changes into its query planning, ensuring that user
-interactions with their data remain accurate and up-to-date.
-
-You can also update the command by editing the command's metadata manually.
-
-## Delete a command
-
-```ddn title="If you no longer need a command, you can delete it:"
-ddn command remove
-```
-
-Along with the command itself, the associated metadata is also removed, and PromptQL will no longer include this command
-in its query planning.
-
-## Reference
-
-You can learn more about commands in the metadata reference [docs](/reference/metadata-reference/commands.mdx).
diff --git a/docs/data-modeling/data-modeling-workflows.mdx b/docs/data-modeling/data-modeling-workflows.mdx
deleted file mode 100644
index cb385675..00000000
--- a/docs/data-modeling/data-modeling-workflows.mdx
+++ /dev/null
@@ -1,29 +0,0 @@
----
-sidebar_label: Data Modeling Workflows
-sidebar_position: 5.2
-description: "Learn about the different workflows for data modeling in PromptQL."
-keywords:
- - hasura ddn
- - data modeling
- - promptql
- - iterate
- - semantic information
- - descriptions
----
-
-# Data Modeling Workflows
-
-Learn how to iterate on your data model, add semantic information, and more.
-
-## Iterating on your data model
-
-When your underlying data model changes, you need to iterate on your data model to reflect the changes.
-
-[Learn more about iterating on your data model](/data-modeling/iterate.mdx)
-
-## Adding semantic information
-
-When you add semantic information to your data model, you can help PromptQL understand your data and create appropriate
-query plans.
-
-[Learn more about semantic information](/data-modeling/semantic-information.mdx)
diff --git a/docs/data-modeling/index.mdx b/docs/data-modeling/index.mdx
deleted file mode 100644
index cf05cda3..00000000
--- a/docs/data-modeling/index.mdx
+++ /dev/null
@@ -1,46 +0,0 @@
----
-sidebar_position: 1
-sidebar_label: Basics
-description:
- "Data modeling with Hasura DDN is simultaneously simple and powerful. Learn how to model your data with Hasura DDN to
- get the best API performance on top of your data."
-keywords:
- - hasura ddn
- - data modeling
-hide_table_of_contents: true
----
-
-import { OverviewTopSectionIconNoVideo } from "@site/src/components/OverviewTopSectionIconNoVideo";
-import { OverviewPlainCard } from "@site/src/components/OverviewPlainCard";
-import Icon from "@site/static/icons/features/data-modeling.svg";
-import Thumbnail from "@site/src/components/Thumbnail";
-
-# Data Modeling
-
-## Introduction
-
-Your PromptQL application is powered by an agentic semantic metadata layer. This approach centralizes all your data
-collections, operations, relationships, and permissions in one place. This makes it easy for your (and PromptQL) to
-organize, modify, secure, reason about, and grow the schema which represents your API.
-
-## Lifecycle
-
-PromptQL uses this semantic metadata layer to define your API schema:
-
-- Data connectors link to your data sources and introspect the source schema.
-- The CLI then uses the introspection results to generate metadata objects.
-- The metadata is "built" by the CLI into a format that the engine service uses to power PromptQL's interactions.
-
-
-
-## Metadata Objects
-
-There are [many types of metadata objects](/reference/metadata-reference/index.mdx) which define your API, but the most
-important ones which form the backbone of your API are:
-
-- [Models](/data-modeling/model.mdx) which read data
-- [Commands](/data-modeling/command.mdx) which modify data
-- [Relationships](/data-modeling/relationship.mdx) which connect data
-- [Permissions](/data-modeling/permissions.mdx) which protect data
-
-We will cover each of these in more detail in the following sections.
diff --git a/docs/data-modeling/model.mdx b/docs/data-modeling/model.mdx
deleted file mode 100644
index fcb88779..00000000
--- a/docs/data-modeling/model.mdx
+++ /dev/null
@@ -1,127 +0,0 @@
----
-sidebar_position: 2
-sidebar_label: "Models read data"
-description: "Models make your data accessible to PromptQL, enabling accurate data interactions and insights."
-keywords:
- - model
- - data modeling
- - PromptQL
- - AI
- - LLM
-toc_max_heading_level: 4
----
-
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-import Thumbnail from "@site/src/components/Thumbnail";
-
-import ModelCreateNativeQueryHowToPostgreSQL from "@site/docs/data-modeling/partials/classic-connectors/postgreSQL/_model-create-native-query-how-to.mdx";
-
-import { PqlChat, User, Pql, QueryPlanComponent } from "@site/src/components/PqlChat/PqlChat";
-
-# Models Empower PromptQL to Understand Your Data
-
-## Introduction
-
-Models are foundational components that enable PromptQL to accurately access and interact with your data. They represent
-entities or collections in your data sources, including tables, views, collections, and native queries, providing the
-semantic understanding PromptQL needs to generate precise query plans and produce meaningful insights from your data.
-
-## Lifecycle
-
-Creating models for your PromptQL's metadata layer involves the following steps:
-
-1. Identify data sources that you want PromptQL to intelligently interact with.
-2. Introspect your data source using the CLI with the relevant data connector to fetch the entity resources.
-3. Add the model to your metadata with the CLI.
-4. Create a build of your application with the CLI.
-5. Serve your build via the packaged distributed query engine, either locally or in the cloud.
-6. Interact with your data through PromptQL in a natural, conversational way.
-
-
-
-## Create a model
-
-To add a model you will need to have a data connector already set up and connected to the data source. Follow the
-relevant tutorial for your data source in [How to Build with PromptQL](/how-to-build-with-promptql/index.mdx) to get to
-that point.
-
-### From a source entity
-
-```ddn title="Introspect your data source:"
-ddn connector introspect
-```
-
-Whenever you update your data source, you can run the above command to fetch the latest resources.
-
-```ddn title="Show the resources discovered from your data source:"
-ddn connector show-resources
-```
-
-```ddn title="This optional step will output a list of resources that the connector discovered in your data source:"
-ddn model add
-```
-
-```ddn title="Or you can optionally add all the models using this wildcard:"
-ddn model add "*"
-```
-
-This will add models with their accompanying metadata definitions to your metadata.
-
-You can now create a build, serve it, and begin having meaningful conversations with your data through PromptQL. With
-robust models in place, PromptQL can create dynamic query plans that accurately address your requests and provide deep
-insights into your data.
-
-:::info Context for CLI commands
-
-Note that the above CLI commands work without also adding the relevant subgraph to the command with the `--subgraph`
-flag because this has been set in the CLI context. You can learn more about creating and switching contexts in the
-[CLI context](/reference/cli/commands/ddn_context.mdx) section.
-
-:::
-
-## Update a model
-
-If you want to update your model to reflect a change that happened in the underlying data source you should first
-introspect to get the latest resources and then update the relevant model.
-
-```ddn title="Introspect your data source:"
-ddn connector introspect
-```
-
-```ddn title="Then, update your existing model:"
-ddn model update
-```
-
-You will see an output which explains how new resources were added or updated in the model.
-
-You can now create a build, serve it, and continue interacting with your data using PromptQL, which will automatically
-adjust its query plans based on the updated model definitions.
-
-You can also update the model by editing the metadata manually.
-
-## Extend a model
-
-A model can be extended to enable PromptQL to understand and navigate relationships between different data entities.
-
-For example, you can extend a model like `Customers` to also include related `Orders` data. This allows PromptQL to
-answer questions like "Show me customer Jane Doe's recent orders" by understanding the relationship between customers
-and orders.
-
-Or you can add custom business logic to a model like `Orders` to compute and return the current currency conversion of
-the total price, enabling PromptQL to provide real-time financial insights across different currencies.
-
-The way this is done is via a `Relationship`. Read more about
-[creating relationships here](/data-modeling/relationship.mdx).
-
-## Delete a model
-
-```ddn title="If you no longer need a model, you can delete it:"
-ddn model remove users
-```
-
-In addition to removing the `Model` object itself, the CLI will also remove the associated metadata definitions.
-
-## Reference
-
-You can learn more about models in the metadata reference [docs](/reference/metadata-reference/models.mdx).
diff --git a/docs/data-modeling/relationship.mdx b/docs/data-modeling/relationship.mdx
deleted file mode 100644
index b32bcd87..00000000
--- a/docs/data-modeling/relationship.mdx
+++ /dev/null
@@ -1,173 +0,0 @@
----
-sidebar_position: 4
-sidebar_label: "Relationships connect data"
-description: "Relationships allow you to connect data across different models for PromptQL to understand and access."
-keywords:
- - relationship
- - data modeling
- - promptql
- - ai
- - llm
----
-
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-import Thumbnail from "@site/src/components/Thumbnail";
-
-# Relationships Connect Data
-
-## Introduction
-
-Relationships allow you to connect your data, enabling PromptQL to understand the semantic connections between your data
-entities and accurately talk to all your data. By defining these relationships, PromptQL can generate intelligent query
-plans that navigate complex data structures to provide meaningful insights.
-
-Examples of how PromptQL uses relationships to deliver powerful insights:
-
-- When asking PromptQL about a customer's purchasing patterns, it can understand the relationship between `Customer`,
- their `Orders`, and each `Product` item in those orders, delivering comprehensive purchasing analysis. (Model to
- Model)
-- When requesting customer behavior analytics, PromptQL can correlate a `Customer` with their app usage metrics from
- another data source, providing cross-data-source insights. (Model to Model in another subgraph or data connector)
-- When analyzing international sales performance, PromptQL can combine `Order` data with live currency conversions from
- an external API through a lambda data connector, delivering real-time financial analysis. (Model to Command)
-
-Relationships can be added between _any_ kind of semantically related models and/or commands. They do not need to be
-related in the data source by, for example, a foreign key. They also do not need to be backed by the same data source or
-be in the same subgraph.
-
-## Lifecycle
-
-Many relationships can be created automatically by the CLI from detected underlying connections such as foreign keys. In
-such cases the lifecycle in creating a relationship in your metadata is as follows:
-
-1. Introspect your data source using the CLI with the relevant data connector to fetch the entity resources.
-2. Add the detected relationships to your metadata with the CLI.
-3. Create a build with the CLI.
-4. Serve your build via the packaged distributed query engine, either locally or in the cloud.
-5. Iterate on your PromptQL experience by repeating this process or by editing your metadata manually as needed.
-
-
-
-If the relationship cannot be detected automatically, you can easily manually create a relationship in your metadata and
-then perform lifecycle steps 3-5 from above as needed.
-
-## Create a relationship
-
-Relationships are defined in metadata from an
-[object type](/reference/metadata-reference/types.mdx#objecttype-objecttype), to a
-[model](/reference/metadata-reference/models.mdx) or [command](/reference/metadata-reference/commands.mdx). But since
-models and commands are also defined with object types, you can think of relationships as being between models and/or
-commands.
-
-The target command can be enabled with a custom piece of business logic on a lambda data connector, or a native mutation
-operation.
-
-### Using the CLI
-
-The CLI and your data connectors will detect many relationships in your data sources automatically, for instance from
-foreign keys in a relational database, and once introspected, you can add them to your metadata.
-
-```ddn title="Introspect your data source:"
-ddn connector introspect
-```
-
-```ddn title="Show the found relationships:"
-ddn connector show-resources
-```
-
-```ddn title="Add a relationship to your metadata:"
-ddn relationship add
-```
-
-Or optionally add all relationships found for a connector at once:
-
-```ddn
-ddn relationship add "*"
-```
-
-:::info Context for CLI commands
-
-Note that the above CLI commands work without also adding the relevant subgraph to the command with the `--subgraph`
-flag because this has been set in the CLI context. You can learn more about creating and switching contexts in the
-[CLI context](/project-configuration/project-management/manage-contexts.mdx) section.
-
-:::
-
-### Manually creating a relationship
-
-Relationships can also be manually added to your metadata.
-
-The [VS Code extension](https://marketplace.visualstudio.com/items?itemName=HasuraHQ.hasura) can help you to author
-relationships.
-
-For example, you can configure a relationship so that when a user asks PromptQL about a Customer's purchasing history,
-it can also access their Orders data.
-
-```yaml title="Create a relationship in your metadata:"
----
-kind: Relationship
-version: v1
-definition:
- sourceType: Customers # The existing source object type which also defines the model
- name: orders # A name we want to use when we query the Orders from the Customer
- description: |
- Links customers to their purchase orders.
- One customer can have multiple orders.
- This is a critical business relationship that supports order history lookups,
- customer purchase analysis, and revenue attribution.
- Historical orders are retained even if customer becomes inactive.
- target:
- model: # The target can be a model or a command
- name: Orders # The existing model that we want to access when we query the Orders from the Customer
- relationshipType: Array # The relationship type which can be Object or Array. Since a customer can have many orders, we use an Array.
- mapping: # The mapping defines which field on the source object type maps to which field on the target model
- - source:
- fieldPath:
- - fieldName: customerId # The existing field on the source object type that we want to map to the target model
- target:
- modelField:
- - fieldName: customerId # The existing field on the target model that we want to map to the source object type
-```
-
-By defining this `Relationship` object, PromptQL will understand that customers and orders are connected, allowing it to
-generate accurate query plans that can navigate from customer data to their associated orders when responding to user
-queries about customer purchasing behavior.
-
-Learn more about the [Relationship](/reference/metadata-reference/relationships.mdx) object.
-
-## Update a relationship
-
-Your underlying data source may change over time. You can update your relationship to reflect these changes.
-
-If you have an automatically detected relationship and a property on the source object type has changed, you can update
-the relationship to reflect this change.
-
-First, update your connector configuration and models.
-
-```ddn title="Update your source introspection:"
-ddn connector introspect
-```
-
-```ddn title="Then, update your model:"
-ddn model update
-```
-
-Now, you can either delete the existing `Relationship` object and use the CLI to add it again:
-
-```ddn title="Delete your existing relationship manually and add it again:"
-ddn relationship add
-```
-
-Or you can update the `Relationship` object manually. Learn more about the
-[Relationship](/reference/metadata-reference/relationships.mdx) object.
-
-## Delete a relationship
-
-If you no longer need a relationship, simply delete the `Relationship` metadata object manually. It is fully
-self-contained.
-
-## Reference
-
-You can learn more about relationships in the metadata reference
-[docs](/reference/metadata-reference/relationships.mdx).
diff --git a/docs/data-modeling/semantic-information.mdx b/docs/data-modeling/semantic-information.mdx
deleted file mode 100644
index 859e8fd2..00000000
--- a/docs/data-modeling/semantic-information.mdx
+++ /dev/null
@@ -1,248 +0,0 @@
----
-title: "Semantic Information"
-description: "Add additional semantic information to DDN project metadata using the description column"
----
-
-# Semantic Information in PromptQL
-
-PromptQL uses an agentic semantic metadata layer to understand your data model and create appropriate query plans. While
-the basic metadata provides structural information, adding semantic descriptions helps the LLM better understand the
-context and purpose of your data model elements.
-
-## Overview
-
-The `description` field can be added to various metadata elements to provide semantic context:
-
-- Models (database tables)
-- Commands (custom functions)
-- Fields (table columns)
-- Arguments (function parameters)
-- Relationships
-- Types
-
-## Adding Descriptions
-
-### Commands {#commands}
-
-When defining custom functions, use the `description` field to explain:
-
-- Purpose of the function
-- Expected inputs and their formats
-- Return value structure
-- Usage examples
-- Any important constraints or limitations
-
-**Example: Web Search Command**
-
-```yaml {8-18}
-kind: Command
-version: v1
-definition:
- name: WebSearch
- graphql:
- rootFieldName: webSearch
- rootFieldKind: Query
- description: |
- Perform a web search using DuckDuckGo and return the results.
- Takes in default input arguments for limit and region.
- limit is the number of results to return, default 10.
- region is the region to search in, default "us-en".
-
- Args:
- search_term (str): The term to search for.
-
- Returns:
- List[Result]: A list of search result objects.
- arguments:
- - name: searchTerm
- type: String!
- description: The search query term to look up. Should be a clear, specific search phrase.
- - name: limit
- type: Int!
- description: Maximum number of search results to return. Must be between 1 and 100.
- - name: region
- type: String!
- description: Geographic region code for search results (e.g., us-en, uk-en).
- source:
- dataConnectorName: duckduckgo
- argumentMapping:
- limit: limit
- region: region
- searchTerm: search_term
- dataConnectorCommand:
- function: web_search
- outputType: "[WebSearch!]!"
-```
-
-### Models (Database Tables) {#models}
-
-For database tables, describe:
-
-- What the table represents
-- Key relationships
-- Important business rules
-- Data lifecycle information
-
-**Example: Customer Table**
-
-```yaml {5-9}
-kind: Model
-version: v1
-definition:
- name: customers
- description: |
- Stores customer information for both individual and business accounts.
- Customers can have multiple addresses and orders.
- Inactive customers are soft-deleted (is_active=false) rather than removed.
- Customer IDs are globally unique across all regions.
- fields:
- - name: id
- type: uuid
- description: Globally unique identifier for the customer. Used across all systems.
- - name: customer_type
- type: String
- description: Type of customer account: 'individual' or 'business'. Affects pricing and service levels.
- - name: is_active
- type: Boolean
- description: |
- Indicates if the customer account is active.
- False means soft-deleted, but records are retained for compliance.
-```
-
-### Fields (Table Columns) {#fields}
-
-For fields, describe:
-
-- Purpose of the field
-- Valid values or ranges
-- Business rules affecting the field
-- Special formats or patterns
-
-**Example: Order Status Field**
-
-```yaml {3-11}
-name: status
-type: String
-description: |
- Current status of the order.
- Possible values:
- - 'pending': Initial state
- - 'processing': Payment confirmed
- - 'shipped': Order dispatched
- - 'delivered': Confirmed receipt
- - 'cancelled': Order cancelled
- Only moves forward except for 'cancelled' state.
-```
-
-### Relationships {#relationships}
-
-Describe the business meaning of relationships and any important constraints.
-
-**Example: Customer-Order Relationship**
-
-```yaml {7-10}
-kind: Relationship
-version: v1
-definition:
- name: customer_orders
- source: customers
- target: orders
- description: |
- Links customers to their orders. One customer can have multiple orders.
- Orders cannot exist without a customer.
- Historical orders are retained even if customer is deactivated.
-```
-
-## Best Practices
-
-1. **Be Specific**
-
- - Use clear, unambiguous language
- - Include specific constraints and rules
- - Mention edge cases and special handling
-
-2. **Structure Descriptions**
-
- - Use consistent formatting
- - Break into sections for complex descriptions
- - Include examples for unclear cases
-
-3. **Include Business Context**
-
- - Explain why, not just what
- - Reference business rules
- - Note dependencies and relationships
-
-4. **Document Constraints**
- - Value ranges and formats
- - Required fields
- - Validation rules
- - Update conditions
-
-## Example: Complete Model with Semantic Information
-
-Here's a comprehensive example showing semantic descriptions at multiple levels:
-
-```yaml {4-9,13,17,21-25,29-32,36-39,44,48}
-kind: Model
-version: v1
-definition:
- name: product_inventory
- description: |
- Manages product inventory across all warehouses.
- Updated in real-time with inventory movements.
- Integrates with order processing and procurement systems.
- Maintains historical inventory levels with daily snapshots.
- fields:
- - name: product_id
- type: uuid
- description: Unique product identifier. References master product catalog.
-
- - name: warehouse_id
- type: uuid
- description: Identifier of the warehouse where product is stored. Foreign key to warehouses table.
-
- - name: quantity_available
- type: Int
- description: |
- Current available quantity for sale.
- Excludes reserved and damaged items.
- Negative values not allowed.
- Updated via inventory_movement table.
-
- - name: reorder_point
- type: Int
- description: |
- Quantity threshold that triggers reorder.
- Calculated weekly based on 30-day moving average of daily sales.
- Must be greater than zero.
-
- - name: last_counted_at
- type: timestamp
- description: |
- Timestamp of last physical inventory count.
- Updated by inventory audit process.
- Should not be more than 30 days old.
-
- relationships:
- - name: warehouse
- target: warehouses
- description: Links to warehouse details. Each product-warehouse combination must be unique.
-
- - name: product
- target: products
- description: Links to product master data. Inactive products still maintain inventory records.
-```
-
-## Impact of Semantic Metadata on PromptQL
-
-Good semantic information helps PromptQL:
-
-- Generate more accurate query plans
-- Better understand business rules and constraints
-- Make appropriate choices for data filtering and aggregation
-- Provide more relevant responses to natural language queries
-- Handle edge cases correctly
-
-The more crisp and relevant context you provide through descriptions, the better PromptQL can understand and work with
-your data model.
diff --git a/docs/data-sources/introspect-a-source.mdx b/docs/data-sources/introspect-a-source.mdx
index b5f972af..aba6393d 100644
--- a/docs/data-sources/introspect-a-source.mdx
+++ b/docs/data-sources/introspect-a-source.mdx
@@ -58,5 +58,5 @@ up-to-date with your source schema.**
## Next steps
With your source introspected and the configuration files populated, you can now start adding this information to your
-agentic semantic metadata layer. Check out the [Data Modeling](/data-modeling/index.mdx) section to begin creating
-models, commands, and relationships for your data.
+agentic semantic metadata layer. Check out the [Data Modeling](/metadata/index.mdx) section to begin creating models,
+commands, and relationships for your data.
diff --git a/docs/help/index.mdx b/docs/help/index.mdx
index efa840b0..cd21e81a 100644
--- a/docs/help/index.mdx
+++ b/docs/help/index.mdx
@@ -23,7 +23,7 @@ keywords:
Start by exploring our [quickstart guide](/quickstart.mdx) to get up and running with PromptQL or dive into the
[tutorials](/how-to-build-with-promptql/index.mdx) for a step-by-step approach to connect PromptQL to your data sources.
Once you're comfortable, expand your knowledge with sections like [data sources](data-sources/index.mdx),
-[data modeling](data-modeling/index.mdx), [auth](auth/index.mdx), and [deployment](deployment/index.mdx) to enhance how
+[data modeling](metadata/index.mdx), [auth](auth/index.mdx), and [deployment](deployment/index.mdx) to enhance how
PromptQL interacts with your data.
### Ask the community
diff --git a/docs/help/security.mdx b/docs/help/security.mdx
index ef54a49f..bfb524eb 100644
--- a/docs/help/security.mdx
+++ b/docs/help/security.mdx
@@ -89,7 +89,7 @@ Hasura DDN employs a robust role-based access control (RBAC) system. You can def
which users or roles can access specific data and operations. This ensures that only authorized users can perform
actions based on their assigned roles.
-[Learn more about permissions](/data-modeling/permissions.mdx).
+[Learn more about permissions](/metadata/permissions.mdx).
## Authentication
diff --git a/docs/how-to-build-with-promptql/_boilerplateDx.mdx b/docs/how-to-build-with-promptql/_boilerplateDx.mdx
index 37ad3e9e..819a0783 100644
--- a/docs/how-to-build-with-promptql/_boilerplateDx.mdx
+++ b/docs/how-to-build-with-promptql/_boilerplateDx.mdx
@@ -33,7 +33,7 @@ It is highly recommended to provide extra natural language descriptions of the r
can better understand your data and create appropriate query plans.
The description field can be added to `Model`, `Command` and `Relationship` metadata objects to provide semantic
-context. See more about [semantic information here](/data-modeling/semantic-information.mdx).
+context.
### Step 7. Create a new build
@@ -103,4 +103,4 @@ Once the PromptQL interface is open, ask a question about your data. For example
### Step 10. Iterate on your source's schema
If something changes in your data source's schema, you can iterate on your data model by following the steps in the
-[iteration guide](/data-modeling/iterate.mdx).
+[iteration guide](/metadata/guides/iterate.mdx).
diff --git a/docs/metadata/_category_.json b/docs/metadata/_category_.json
new file mode 100644
index 00000000..26bfbe93
--- /dev/null
+++ b/docs/metadata/_category_.json
@@ -0,0 +1,8 @@
+{
+ "label": "Semantic Metadata",
+ "position": 4,
+ "className": "metadata",
+ "customProps": {
+ "sidebar_pathname": "metadata"
+ }
+}
diff --git a/docs/metadata/command.mdx b/docs/metadata/command.mdx
new file mode 100644
index 00000000..846de2a7
--- /dev/null
+++ b/docs/metadata/command.mdx
@@ -0,0 +1,118 @@
+---
+sidebar_position: 4
+sidebar_label: "Write data"
+description: "Commands allow PromptQL to act on your data in various data sources."
+toc_max_heading_level: 4
+keywords:
+ - command
+ - data modeling
+ - promptql
+---
+
+# Write Data
+
+## Introduction
+
+In PromptQL, **commands** let you call custom functions or procedures from your data sources, usually to mutate data.
+
+While commands _can_ handle reads, you’ll mostly reach for them when you need to perform write operations on your data
+source _or_ when executing custom business logic. You decide whether they're exposed as queries or mutations for
+PromptQL, based on how you configure them.
+
+```yaml title="An example command for inserting a user:"
+kind: Command
+version: v1
+definition:
+ name: create_user
+ description: |
+ Creates a new user in the system. This command is typically used when someone registers
+ for the app or is added manually by an admin. It captures core details like:
+ - name
+ - email
+ This is often the first step before establishing relationships with sessions,
+ subscriptions, or other user-linked resources.
+ outputType: action_response!
+ arguments:
+ - name: name
+ type: String!
+ - name: email
+ type: String!
+ source:
+ dataConnectorName: operations
+ dataConnectorCommand:
+ procedure: create_user
+```
+
+## Lifecycle
+
+### Create a command
+
+To add a command you will need to have a data connector which has already introspected the data source. Follow the
+relevant tutorial in [How to Build with PromptQL](/how-to-build-with-promptql/index.mdx) to get to that point.
+
+```ddn title="Add your command by passing the connector's and command's names:"
+# Alternatively, you can add all commands: ddn command add "*"
+
+ddn command add
+```
+
+:::tip Not sure which commands you have?
+
+You can see a list of all available resources using the CLI:
+
+```ddn
+ddn connector show-resources
+```
+
+:::
+
+For each command, you'll find an HML file included in the relevant `metadata` directory for your connected data source.
+
+**Typically, a particular model will have corresponding commands for inserts, updates, and deletes.** This gives
+PromptQL the power to act as a write layer for your API, letting you execute domain-specific operations directly against
+your connected data sources.
+
+You can now [create a build](/reference/cli/commands/ddn_supergraph_build.mdx), serve it, and begin manipulating the
+data underlying the command through PromptQL.
+
+### Update a command
+
+When your underlying data source changes, you'll need to update the commands available to PromptQL to ensure continued
+accuracy in its operations:
+
+```ddn title="Re-introspect your data source:"
+ddn connector introspect
+```
+
+```ddn title="Then, update your existing command:"
+ddn command update
+```
+
+You will see an output which explains how new resources were added or updated in the command.
+
+You can now [create a build](/reference/cli/commands/ddn_supergraph_build.mdx), serve it, and continue interacting with
+the data it represents using PromptQL, which will automatically adjust its query plans based on the updated command
+definitions.
+
+:::tip You can manually edit metadata!
+
+You can also update the command by manually editing the metadata. To avoid errors, we recommend using the
+[VS Code extension](https://marketplace.visualstudio.com/items?itemName=HasuraHQ.hasura) to validate your changes.
+
+:::
+
+### Delete a command
+
+```ddn title="If you no longer need a command, you can delete it:"
+ddn command remove
+```
+
+Along with the command itself, the associated metadata is also removed, and PromptQL will no longer include this command
+in its query planning.
+
+## Next steps
+
+- If you've added your first command, check out [relationships for connecting data](/metadata/relationship.mdx) next.
+- Business logic is exposed as commands written in TypeScript, Go, or Python. Learn more about adding this functionality
+ by [connecting a lambda connector](/business-logic/index.mdx).
+- You can learn more about commands in the metadata reference [docs](/reference/metadata-reference/commands.mdx).
diff --git a/docs/metadata/guides/_category_.json b/docs/metadata/guides/_category_.json
new file mode 100644
index 00000000..6b51b67c
--- /dev/null
+++ b/docs/metadata/guides/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "Guides",
+ "position": 6
+}
diff --git a/docs/metadata/guides/index.mdx b/docs/metadata/guides/index.mdx
new file mode 100644
index 00000000..627f2fb7
--- /dev/null
+++ b/docs/metadata/guides/index.mdx
@@ -0,0 +1,19 @@
+---
+sidebar_position: 1
+sidebar_label: Guides
+description: "See step-by-step guides for working with your semantic metadata layer."
+keywords:
+ - hasura ddn
+ - semantic metadata
+---
+
+# Guides
+
+## Introduction
+
+In this section, you'll find step-by-step examples of how to work with your semantic metadata layer.
+
+## Learn more
+
+- [Iterate on your data model](/metadata/guides/iterate.mdx)
+- [Recast types at the metadata layer](/metadata/guides/typecasting.mdx)
diff --git a/docs/data-modeling/iterate.mdx b/docs/metadata/guides/iterate.mdx
similarity index 96%
rename from docs/data-modeling/iterate.mdx
rename to docs/metadata/guides/iterate.mdx
index f798c3ed..10d497de 100644
--- a/docs/data-modeling/iterate.mdx
+++ b/docs/metadata/guides/iterate.mdx
@@ -86,8 +86,8 @@ ddn relationship add my_connector "*"
It's highly recommended to provide extra natural language descriptions of the resources in your project so that the
PromptQL can better understand your data and create appropriate query plans.
-The description field can be added to `Model`, `Command` and `Relationship` metadata elements to provide semantic
-context. See more about [semantic information here](/data-modeling/semantic-information.mdx).
+The description field can be added to `Model`, `Command` and `Relationship` metadata objects to provide semantic
+context.
#### Rebuild
diff --git a/docs/data-modeling/typecasting.mdx b/docs/metadata/guides/typecasting.mdx
similarity index 100%
rename from docs/data-modeling/typecasting.mdx
rename to docs/metadata/guides/typecasting.mdx
diff --git a/docs/metadata/index.mdx b/docs/metadata/index.mdx
new file mode 100644
index 00000000..87b42159
--- /dev/null
+++ b/docs/metadata/index.mdx
@@ -0,0 +1,53 @@
+---
+sidebar_position: 1
+sidebar_label: Basics
+description:
+ "Data modeling with Hasura DDN is simultaneously simple and powerful. Learn how to model your data with Hasura DDN to
+ get the best API performance on top of your data."
+keywords:
+ - hasura ddn
+ - semantic metadata
+hide_table_of_contents: true
+---
+
+# Semantic Metadata
+
+## Introduction
+
+Your PromptQL application is powered by an agentic semantic metadata layer. This approach centralizes all your data
+collections, operations, relationships, and permissions in one place. This makes it easy for you (and PromptQL) to
+organize, modify, secure, reason about, and grow the schema which represents your API.
+
+## Lifecycle
+
+PromptQL uses this semantic metadata layer to define your API schema:
+
+- Data connectors link to your data sources and introspect the source schema.
+- The CLI then uses the introspection results to generate metadata objects.
+- The metadata is then composed by the CLI into an immutable build, representing a snapshot in time, which is served by
+ the distributed query engine to power PromptQL's interactions.
+
+```mermaid
+flowchart LR
+ DataSource["Data Source
PostgreSQL, MongoDB,
REST endpoint,
custom business logic,
etc."] --> DataConnector["Data Connector
Software which connects
your project to
the data source."]
+
+ DataConnector --> Introspection["Introspection
Representation of
the data source
generated by the
data connector."]
+
+ Introspection --> Metadata["Metadata
HML definition of
the your API in
the form of metadata
objects."]
+
+ Metadata --> Build["Build
Collection of all
the metadata in a
form which the
query engine can
use to serve the
API."]
+
+ Build -.->|"Re-introspect after iterating on your data source"| Introspection
+```
+
+## Metadata Objects
+
+There are [many types of metadata objects](/reference/metadata-reference/index.mdx) which define your API, but the most
+important ones which form the backbone of your application are:
+
+- [Models](/metadata/model.mdx) which read data
+- [Commands](/metadata/command.mdx) which modify data
+- [Relationships](/metadata/relationship.mdx) which connect data
+- [Permissions](/metadata/permissions.mdx) which protect data
+
+We will cover each of these in more detail in the following sections.
diff --git a/docs/metadata/model.mdx b/docs/metadata/model.mdx
new file mode 100644
index 00000000..3a47a7c8
--- /dev/null
+++ b/docs/metadata/model.mdx
@@ -0,0 +1,118 @@
+---
+sidebar_position: 2
+sidebar_label: "Read data"
+description: "Models make your data accessible to PromptQL, enabling accurate data interactions and insights."
+keywords:
+ - model
+ - data modeling
+ - PromptQL
+ - AI
+ - LLM
+toc_max_heading_level: 4
+---
+
+# Read Data
+
+## Introduction
+
+PromptQL uses **models** to access and interpret data from your sources.
+
+These models can be tables, views, collections, or native queries. They help PromptQL understand the data's structure
+and meaning. This understanding allows PromptQL to create accurate query plans and extract valuable insights from your
+data.
+
+```yml title="An example model for a users table:"
+kind: Model
+version: v2
+definition:
+ name: users
+ description: |
+ Represents people who have registered for the app. This model stores core info like:
+ - name
+ - email
+ - ID
+ Along with any other metadata tied to the user. It’s often the starting point for building
+ relationships with other models—things like sessions, subscriptions, or audit logs.
+ objectType: users
+ source:
+ dataConnectorName: operations
+ collection: users
+```
+
+Other metadata exists when you create a model, but this is the core object for reading data from a data source.
+
+## Lifecycle
+
+### Create a model
+
+To add a model you will need to have a data connector which has already introspected the data source. Follow the
+relevant tutorial in [How to Build with PromptQL](/how-to-build-with-promptql/index.mdx) to get to that point.
+
+```ddn title="Add your model by passing the connector's and model's names:"
+# Alternatively, you can add all models: ddn model add "*"
+
+ddn model add
+```
+
+:::tip Not sure which models you have?
+
+You can see a list of all available resources using the CLI:
+
+```ddn
+ddn connector show-resources
+```
+
+:::
+
+For each model, you'll find an HML file included in the relevant `metadata` directory for your connected data source.
+
+You can now [create a build](/reference/cli/commands/ddn_supergraph_build.mdx), serve it, and begin having meaningful
+conversations with the data it represents through PromptQL. With robust models in place, PromptQL can create dynamic
+query plans that accurately address your requests and provide deep insights into your data.
+
+:::info Context for CLI commands
+
+Note that the above CLI commands work without also adding the relevant subgraph to the command with the `--subgraph`
+flag because this has been set in the CLI context. You can learn more about creating and switching contexts in the
+[CLI context](/reference/cli/commands/ddn_context.mdx) section.
+
+:::
+
+### Update a model
+
+If you want to update your model to reflect a change that happened in the underlying data source you should first
+introspect to get the latest resources and then update the relevant model.
+
+```ddn title="Re-introspect your data source:"
+ddn connector introspect
+```
+
+```ddn title="Then, update your existing model:"
+ddn model update
+```
+
+You will see an output which explains how new resources were added or updated in the model.
+
+You can now [create a build](/reference/cli/commands/ddn_supergraph_build.mdx), serve it, and continue interacting with
+the data it represents using PromptQL, which will automatically adjust its query plans based on the updated model
+definitions.
+
+:::tip You can manually edit metadata!
+
+You can also update the model by manually editing the metadata. To avoid errors, we recommend using the
+[VS Code extension](https://marketplace.visualstudio.com/items?itemName=HasuraHQ.hasura) to validate your changes.
+
+:::
+
+### Delete a model
+
+```ddn title="If you no longer need a model, you can delete it:"
+ddn model remove users
+```
+
+In addition to removing the `Model` object itself, the CLI will also remove the associated metadata definitions.
+
+## Next steps
+
+- If you've added your first model, check out [commands for writing data](/metadata/command.mdx) next.
+- You can learn more about models in the metadata reference [docs](/reference/metadata-reference/models.mdx).
diff --git a/docs/data-modeling/partials/classic-connectors/clickHouse/_command-create-native-operation-how-to.mdx b/docs/metadata/partials/classic-connectors/clickHouse/_command-create-native-operation-how-to.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/clickHouse/_command-create-native-operation-how-to.mdx
rename to docs/metadata/partials/classic-connectors/clickHouse/_command-create-native-operation-how-to.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/clickHouse/_model-create-native-query-how-to.mdx b/docs/metadata/partials/classic-connectors/clickHouse/_model-create-native-query-how-to.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/clickHouse/_model-create-native-query-how-to.mdx
rename to docs/metadata/partials/classic-connectors/clickHouse/_model-create-native-query-how-to.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/clickHouse/_model-create-native-query-tutorial.mdx b/docs/metadata/partials/classic-connectors/clickHouse/_model-create-native-query-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/clickHouse/_model-create-native-query-tutorial.mdx
rename to docs/metadata/partials/classic-connectors/clickHouse/_model-create-native-query-tutorial.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/clickHouse/_model-create-tutorial.mdx b/docs/metadata/partials/classic-connectors/clickHouse/_model-create-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/clickHouse/_model-create-tutorial.mdx
rename to docs/metadata/partials/classic-connectors/clickHouse/_model-create-tutorial.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/clickHouse/_relationship-create-model-to-model.mdx b/docs/metadata/partials/classic-connectors/clickHouse/_relationship-create-model-to-model.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/clickHouse/_relationship-create-model-to-model.mdx
rename to docs/metadata/partials/classic-connectors/clickHouse/_relationship-create-model-to-model.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/mongoDB/_command-create-native-operation-how-to.mdx b/docs/metadata/partials/classic-connectors/mongoDB/_command-create-native-operation-how-to.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/mongoDB/_command-create-native-operation-how-to.mdx
rename to docs/metadata/partials/classic-connectors/mongoDB/_command-create-native-operation-how-to.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/mongoDB/_command-create-native-operation-tutorial.mdx b/docs/metadata/partials/classic-connectors/mongoDB/_command-create-native-operation-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/mongoDB/_command-create-native-operation-tutorial.mdx
rename to docs/metadata/partials/classic-connectors/mongoDB/_command-create-native-operation-tutorial.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/mongoDB/_command-create-tutorial.mdx b/docs/metadata/partials/classic-connectors/mongoDB/_command-create-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/mongoDB/_command-create-tutorial.mdx
rename to docs/metadata/partials/classic-connectors/mongoDB/_command-create-tutorial.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/mongoDB/_command-update-tutorial.mdx b/docs/metadata/partials/classic-connectors/mongoDB/_command-update-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/mongoDB/_command-update-tutorial.mdx
rename to docs/metadata/partials/classic-connectors/mongoDB/_command-update-tutorial.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/mongoDB/_model-create-native-query-how-to.mdx b/docs/metadata/partials/classic-connectors/mongoDB/_model-create-native-query-how-to.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/mongoDB/_model-create-native-query-how-to.mdx
rename to docs/metadata/partials/classic-connectors/mongoDB/_model-create-native-query-how-to.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/mongoDB/_model-create-native-query-tutorial.mdx b/docs/metadata/partials/classic-connectors/mongoDB/_model-create-native-query-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/mongoDB/_model-create-native-query-tutorial.mdx
rename to docs/metadata/partials/classic-connectors/mongoDB/_model-create-native-query-tutorial.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/mongoDB/_model-create-tutorial.mdx b/docs/metadata/partials/classic-connectors/mongoDB/_model-create-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/mongoDB/_model-create-tutorial.mdx
rename to docs/metadata/partials/classic-connectors/mongoDB/_model-create-tutorial.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/mongoDB/_relationship-create-model-to-model.mdx b/docs/metadata/partials/classic-connectors/mongoDB/_relationship-create-model-to-model.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/mongoDB/_relationship-create-model-to-model.mdx
rename to docs/metadata/partials/classic-connectors/mongoDB/_relationship-create-model-to-model.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/postgreSQL/_command-create-native-operation-how-to.mdx b/docs/metadata/partials/classic-connectors/postgreSQL/_command-create-native-operation-how-to.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/postgreSQL/_command-create-native-operation-how-to.mdx
rename to docs/metadata/partials/classic-connectors/postgreSQL/_command-create-native-operation-how-to.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/postgreSQL/_command-create-native-operation-tutorial.mdx b/docs/metadata/partials/classic-connectors/postgreSQL/_command-create-native-operation-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/postgreSQL/_command-create-native-operation-tutorial.mdx
rename to docs/metadata/partials/classic-connectors/postgreSQL/_command-create-native-operation-tutorial.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/postgreSQL/_command-create-tutorial.mdx b/docs/metadata/partials/classic-connectors/postgreSQL/_command-create-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/postgreSQL/_command-create-tutorial.mdx
rename to docs/metadata/partials/classic-connectors/postgreSQL/_command-create-tutorial.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/postgreSQL/_command-update-tutorial.mdx b/docs/metadata/partials/classic-connectors/postgreSQL/_command-update-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/postgreSQL/_command-update-tutorial.mdx
rename to docs/metadata/partials/classic-connectors/postgreSQL/_command-update-tutorial.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/postgreSQL/_model-create-native-query-how-to.mdx b/docs/metadata/partials/classic-connectors/postgreSQL/_model-create-native-query-how-to.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/postgreSQL/_model-create-native-query-how-to.mdx
rename to docs/metadata/partials/classic-connectors/postgreSQL/_model-create-native-query-how-to.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/postgreSQL/_model-create-native-query-tutorial.mdx b/docs/metadata/partials/classic-connectors/postgreSQL/_model-create-native-query-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/postgreSQL/_model-create-native-query-tutorial.mdx
rename to docs/metadata/partials/classic-connectors/postgreSQL/_model-create-native-query-tutorial.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/postgreSQL/_model-create-tutorial.mdx b/docs/metadata/partials/classic-connectors/postgreSQL/_model-create-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/postgreSQL/_model-create-tutorial.mdx
rename to docs/metadata/partials/classic-connectors/postgreSQL/_model-create-tutorial.mdx
diff --git a/docs/data-modeling/partials/classic-connectors/postgreSQL/_relationship-create-model-to-model.mdx b/docs/metadata/partials/classic-connectors/postgreSQL/_relationship-create-model-to-model.mdx
similarity index 100%
rename from docs/data-modeling/partials/classic-connectors/postgreSQL/_relationship-create-model-to-model.mdx
rename to docs/metadata/partials/classic-connectors/postgreSQL/_relationship-create-model-to-model.mdx
diff --git a/docs/data-modeling/partials/lambda-connectors/go/_command-create-native-operation-how-to.mdx b/docs/metadata/partials/lambda-connectors/go/_command-create-native-operation-how-to.mdx
similarity index 100%
rename from docs/data-modeling/partials/lambda-connectors/go/_command-create-native-operation-how-to.mdx
rename to docs/metadata/partials/lambda-connectors/go/_command-create-native-operation-how-to.mdx
diff --git a/docs/data-modeling/partials/lambda-connectors/go/_command-create-tutorial.mdx b/docs/metadata/partials/lambda-connectors/go/_command-create-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/lambda-connectors/go/_command-create-tutorial.mdx
rename to docs/metadata/partials/lambda-connectors/go/_command-create-tutorial.mdx
diff --git a/docs/data-modeling/partials/lambda-connectors/go/_command-update-tutorial.mdx b/docs/metadata/partials/lambda-connectors/go/_command-update-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/lambda-connectors/go/_command-update-tutorial.mdx
rename to docs/metadata/partials/lambda-connectors/go/_command-update-tutorial.mdx
diff --git a/docs/data-modeling/partials/lambda-connectors/python/_command-create-native-operation-how-to.mdx b/docs/metadata/partials/lambda-connectors/python/_command-create-native-operation-how-to.mdx
similarity index 100%
rename from docs/data-modeling/partials/lambda-connectors/python/_command-create-native-operation-how-to.mdx
rename to docs/metadata/partials/lambda-connectors/python/_command-create-native-operation-how-to.mdx
diff --git a/docs/data-modeling/partials/lambda-connectors/python/_command-create-tutorial.mdx b/docs/metadata/partials/lambda-connectors/python/_command-create-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/lambda-connectors/python/_command-create-tutorial.mdx
rename to docs/metadata/partials/lambda-connectors/python/_command-create-tutorial.mdx
diff --git a/docs/data-modeling/partials/lambda-connectors/python/_command-update-tutorial.mdx b/docs/metadata/partials/lambda-connectors/python/_command-update-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/lambda-connectors/python/_command-update-tutorial.mdx
rename to docs/metadata/partials/lambda-connectors/python/_command-update-tutorial.mdx
diff --git a/docs/data-modeling/partials/lambda-connectors/typescript/_command-create-native-operation-how-to.mdx b/docs/metadata/partials/lambda-connectors/typescript/_command-create-native-operation-how-to.mdx
similarity index 100%
rename from docs/data-modeling/partials/lambda-connectors/typescript/_command-create-native-operation-how-to.mdx
rename to docs/metadata/partials/lambda-connectors/typescript/_command-create-native-operation-how-to.mdx
diff --git a/docs/data-modeling/partials/lambda-connectors/typescript/_command-create-tutorial.mdx b/docs/metadata/partials/lambda-connectors/typescript/_command-create-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/lambda-connectors/typescript/_command-create-tutorial.mdx
rename to docs/metadata/partials/lambda-connectors/typescript/_command-create-tutorial.mdx
diff --git a/docs/data-modeling/partials/lambda-connectors/typescript/_command-update-tutorial.mdx b/docs/metadata/partials/lambda-connectors/typescript/_command-update-tutorial.mdx
similarity index 100%
rename from docs/data-modeling/partials/lambda-connectors/typescript/_command-update-tutorial.mdx
rename to docs/metadata/partials/lambda-connectors/typescript/_command-update-tutorial.mdx
diff --git a/docs/data-modeling/permissions.mdx b/docs/metadata/permissions.mdx
similarity index 84%
rename from docs/data-modeling/permissions.mdx
rename to docs/metadata/permissions.mdx
index d64ea3f2..53a09cf9 100644
--- a/docs/data-modeling/permissions.mdx
+++ b/docs/metadata/permissions.mdx
@@ -1,6 +1,6 @@
---
sidebar_position: 5
-sidebar_label: "Permissions protect data"
+sidebar_label: "Protect data"
description:
"Permissions allow you to control who can access your data and what they can do with it when using PromptQL."
keywords:
@@ -11,11 +11,11 @@ toc_max_heading_level: 4
sidebar_class_name: sidebar-divider-bottom
---
-# Permissions Protect Data
+# Protect Data
## Introduction
-Permissions keep data secure by allowing you to control what data can be accessed through PromptQL conversations by
+**Permissions** keep data secure by allowing you to control what data can be accessed through PromptQL conversations by
which user roles. This ensures that when users talk to their data using PromptQL, they only see the information they're
authorized to access.
@@ -33,19 +33,14 @@ the `admin` role by default.
All other permissions for all other user roles must be added manually.
-## Create permissions
+## Create a permission
### Row access
You can create a `ModelPermission` object to implement row-level security and restrict which rows a user can access
through PromptQL.
-For example, to only allow users to access their own records in the `Users` table when talking to their data through
-PromptQL:
-
-```yaml title=""
----
-# e.g., Users.hml
+```yaml title="For example, to only allow users to access their own records in the Users table when talking to their data through PromptQL:"
kind: ModelPermissions
version: v1
definition:
@@ -77,8 +72,6 @@ To restrict which fields can be accessed through PromptQL conversations, you can
Below, the user role can only access the `name` field, not the `id` field which the admin role can.
```yaml title="The user role can only access their name field:"
-# e.g., Users.hml
----
kind: TypePermissions
version: v1
definition:
@@ -104,8 +97,6 @@ To determine which commands can be executed by which roles when interacting with
`CommandPermission` object.
```yaml title="In this example, we'll make it so a user can update their own record:"
-# e.g., UpdateUsersById.hml
----
kind: CommandPermissions
version: v1
definition:
@@ -126,20 +117,22 @@ definition:
When a user asks PromptQL to update their information, these permissions ensure that they can only modify their own
records.
-## Update permissions
+## Update a permission
Since all permissions are stored in metadata, you can use your text editor to find and update them easily.
For example, to check everything which the `user` role can access when talking to data through PromptQL, search for
`- role: user` and analyze the results.
-## Deleting permissions
+## Delete a permission
If you no longer need a role, find all mentions of it in your metadata and remove them all.
If you no longer need a particular permission, simply remove it from the relevant `ModelPermissions`, `TypePermissions`,
or `CommandPermissions` object.
-## Reference
+## Next steps
-You can learn more about permissions in the metadata reference [docs](/reference/metadata-reference/permissions.mdx).
+- Now that you've been through the major building blocks of your semantic metadata layer, check out the
+ [business logic section](/business-logic/index.mdx) to learn how to place more tools in PromptQL's toolbox.
+- You can learn more about permissions in the metadata reference [docs](/reference/metadata-reference/permissions.mdx).
diff --git a/docs/metadata/relationship.mdx b/docs/metadata/relationship.mdx
new file mode 100644
index 00000000..0ef2eb5b
--- /dev/null
+++ b/docs/metadata/relationship.mdx
@@ -0,0 +1,117 @@
+---
+sidebar_position: 4
+sidebar_label: "Relate data"
+description: "Relationships allow you to connect data across different models for PromptQL to understand and access."
+keywords:
+ - relationship
+ - data modeling
+ - promptql
+ - ai
+ - llm
+---
+
+# Relate Data
+
+## Introduction
+
+**Relationships** allow you to connect your data, enabling PromptQL to understand the semantic connections between your
+data entities and accurately talk to all your data. By defining these relationships, PromptQL can generate intelligent
+query plans that navigate complex data structures to provide meaningful insights.
+
+Relationships are defined in metadata from an
+[object type](/reference/metadata-reference/types.mdx#objecttype-objecttype), to a
+[model](/reference/metadata-reference/models.mdx) or [command](/reference/metadata-reference/commands.mdx). But since
+models and commands are also defined with object types, you can think of relationships as being between models and/or
+commands.
+
+```yaml title="An example relationship for a users table to a sessions table:"
+kind: Relationship
+version: v1
+definition:
+ name: user
+ description: |
+ Associates a session with the user who initiated it. This relationship connects each record in the
+ `sessions` model to a corresponding entry in the `users` model using the `userId` field. It's typically
+ used to fetch user details—such as name, email, or role—when querying session data.
+ sourceType: sessions
+ target:
+ model:
+ name: users
+ subgraph: operations
+ relationshipType: Object
+ mapping:
+ - source:
+ fieldPath:
+ - fieldName: userId
+ target:
+ modelField:
+ - fieldName: id
+```
+
+## Lifecycle
+
+### Create a relationship
+
+To add a relationship you will need to have a data connector which has already introspected the data source. Follow the
+relevant tutorial in [How to Build with PromptQL](/how-to-build-with-promptql/index.mdx) to get to that point.
+
+```ddn title="Add your relationship by passing the connector's and relationship's names:"
+# Alternatively, you can add all relationships: ddn relationship add "*"
+
+ddn relationship add
+```
+
+:::tip Not sure which relationships you have?
+
+Relationships are generally available for any foreign-key values defined in your data source. You can see a list of all
+available resources using the CLI:
+
+```ddn
+ddn connector show-resources
+```
+
+:::
+
+For each relationship, you'll find a metadata object added in the relevant parent model's HML file.
+
+You can now [create a build](/reference/cli/commands/ddn_supergraph_build.mdx), serve it, and begin having meaningful
+conversations with the related data through PromptQL. With explicitly defined relationships in place, PromptQL can
+create dynamic query plans that accurately address your requests and provide deep insights into and across your data.
+
+### Update a relationship
+
+Your underlying data source may change over time. You can update your relationship to reflect these changes.
+
+If you have an automatically-detected relationship and a property on the source object type has changed, you can update
+the relationship to reflect this change.
+
+First, update your connector configuration and models.
+
+```ddn title="Re-introspect your source:"
+ddn connector introspect
+```
+
+```ddn title="Then, update your model:"
+ddn model update
+```
+
+Now, you can either delete the existing `Relationship` object and use the CLI to add it again:
+
+```ddn title="Delete your existing relationship manually and add it again:"
+ddn relationship add
+```
+
+Or you can update the `Relationship` object manually. Learn more about the
+[Relationship](/reference/metadata-reference/relationships.mdx) object.
+
+### Delete a relationship
+
+If you no longer need a relationship, simply delete the `Relationship` metadata object manually. It is fully
+self-contained.
+
+## Next steps
+
+- If you're comfortable with relationships, check out [permissions](/metadata/permissions.mdx) next to get a better idea
+ of how to restrict access and manipulation of connected data.
+- You can learn more about relationships in the metadata reference
+ [docs](/reference/metadata-reference/relationships.mdx).
diff --git a/docs/private-ddn/create-a-project-on-a-data-plane.mdx b/docs/private-ddn/create-a-project-on-a-data-plane.mdx
index 7e3cd020..941a8064 100644
--- a/docs/private-ddn/create-a-project-on-a-data-plane.mdx
+++ b/docs/private-ddn/create-a-project-on-a-data-plane.mdx
@@ -82,8 +82,7 @@ ddn command add '*'
ddn relationship add '*'
```
-You'll see metadata files generated for each entity in your data source. You can learn more
-[here](/data-modeling/index.mdx).
+You'll see metadata files generated for each entity in your data source. You can learn more [here](/metadata/index.mdx).
## Step 5. Create a new local build
@@ -113,5 +112,5 @@ When this process is complete, the CLI will return a link to the hosted applicat
## Next steps
-With your first project created, learn more about how Hasura handles [data modeling](/data-modeling/index.mdx) before
-diving into advanced features.
+With your first project created, learn more about how Hasura handles [data modeling](/metadata/index.mdx) before diving
+into advanced features.
diff --git a/docs/private-ddn/ddn-workspace.mdx b/docs/private-ddn/ddn-workspace.mdx
index 98978649..c0821723 100644
--- a/docs/private-ddn/ddn-workspace.mdx
+++ b/docs/private-ddn/ddn-workspace.mdx
@@ -164,8 +164,7 @@ ddn command add '*'
ddn relationship add '*'
```
-Metadata files will be generated for each entity in your data source. You can learn more
-[here](/data-modeling/index.mdx).
+Metadata files will be generated for each entity in your data source. You can learn more [here](/metadata/index.mdx).
:::info Note
diff --git a/docs/project-configuration/promptql-config/system-instructions.mdx b/docs/project-configuration/promptql-config/system-instructions.mdx
index 8b137cb6..7fb8fb8e 100644
--- a/docs/project-configuration/promptql-config/system-instructions.mdx
+++ b/docs/project-configuration/promptql-config/system-instructions.mdx
@@ -73,6 +73,6 @@ However, through connecting data sources and writing your own custom business lo
which PromptQL can use. While context in the form of system instructions is helpful, you can explain with greater
detail—and with much tighter scope—what each tools does using metadata descriptions.
-Learn more [here](/data-modeling/semantic-information.mdx).
+Learn more [here](/metadata/index.mdx).
:::
diff --git a/docs/recipes/tutorials/weaviate.mdx b/docs/recipes/tutorials/weaviate.mdx
index 7dba92f5..0631dee4 100644
--- a/docs/recipes/tutorials/weaviate.mdx
+++ b/docs/recipes/tutorials/weaviate.mdx
@@ -201,4 +201,4 @@ Historical movies
## Iterating on the Python Code and Logic
-If you need to iterate on your code or schema, check out the [iteration guide](/data-modeling/iterate.mdx).
+If you need to iterate on your code or schema, check out the [iteration guide](/metadata/guides/iterate.mdx).
diff --git a/src/theme/DocSidebar/categories.ts b/src/theme/DocSidebar/categories.ts
index b96c7aaf..dc1f215c 100644
--- a/src/theme/DocSidebar/categories.ts
+++ b/src/theme/DocSidebar/categories.ts
@@ -12,7 +12,7 @@ export const CATEGORY_CONFIG: Record = {
},
coreConcepts: {
title: 'Core Concepts',
- directories: ['architecture', 'data-modeling', 'data-sources', 'business-logic', 'auth'],
+ directories: ['architecture', 'data-sources', 'metadata', 'business-logic', 'auth'],
exactMatch: false,
},
buildingApps: {
diff --git a/static/img/data-modeling/ddn-cli-process.png b/static/img/metadata/ddn-cli-process.png
similarity index 100%
rename from static/img/data-modeling/ddn-cli-process.png
rename to static/img/metadata/ddn-cli-process.png