Docs: Update relationships

Author: robertjdominguez

docs/metadata/relationship.mdx

@@ -10,142 +10,62 @@ keywords:
   - llm
 ---
 
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-import Thumbnail from "@site/src/components/Thumbnail";
-
-# Relationships Connect Data
+# 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.
-
-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.
-
-<Thumbnail src="/img/metadata/ddn-cli-process.png" alt="Data modeling lifecycle" width="1000px" />
-
-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** 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.
 
-The target command can be enabled with a custom piece of business logic on a lambda data connector, or a native mutation
-operation.
+TODO: Example
 
-### Using the CLI
+## Lifecycle
 
-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.
+### Create a relationship
 
-```ddn title="Introspect your data source:"
-ddn connector introspect <connector_name>
-```
+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="Show the found relationships:"
-ddn connector show-resources <connector_name>
-```
+```ddn title="Add your relationship by passing the connector's and relationship's names:"
+# Alternatively, you can add all relationships: ddn relationship add <connector_link_name> "*"
 
-```ddn title="Add a relationship to your metadata:"
-ddn relationship add <connector_link_name> <collection_name>
+ddn relationship add <connector_link_name> <relationship_name>
 ```
 
-Or optionally add all relationships found for a connector at once:
+:::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 relationship add <connector_link_name> "*"
+ddn connector show-resources <connector_name>
 ```
 
-:::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.
+For each relationship, you'll find a metadata object added in the relevant parent model's HML file.
 
-Learn more about the [Relationship](/reference/metadata-reference/relationships.mdx) object.
+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
+### 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
+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 title="Re-introspect your source:"
 ddn connector introspect <connector_name>
 ```
 
@@ -162,12 +82,12 @@ ddn relationship add <connector_link_name> <collection_name>
 Or you can update the `Relationship` object manually. Learn more about the
 [Relationship](/reference/metadata-reference/relationships.mdx) object.
 
-## Delete a relationship
+### Delete a relationship
 
 If you no longer need a relationship, simply delete the `Relationship` metadata object manually. It is fully
 self-contained.
 
-## Reference
+## Next steps
 
 You can learn more about relationships in the metadata reference
 [docs](/reference/metadata-reference/relationships.mdx).