From eca97e6985455e28961e5e022daf1f310c7aa3ab Mon Sep 17 00:00:00 2001
From: Natalie Fiann <Natalie.Fiann@dbtlabs.com>
Date: Fri, 20 Sep 2024 12:04:46 +0100
Subject: [PATCH] Updated constraints doc to include the new recommended syntax

---
 .../resource-properties/constraints.md        | 78 ++++++++++++++++++-
 1 file changed, 74 insertions(+), 4 deletions(-)

diff --git a/website/docs/reference/resource-properties/constraints.md b/website/docs/reference/resource-properties/constraints.md
index ff52a1fbcf..a354702d1a 100644
--- a/website/docs/reference/resource-properties/constraints.md
+++ b/website/docs/reference/resource-properties/constraints.md
@@ -11,6 +11,8 @@ Constraints require the declaration and enforcement of a model [contract](/refer
 
 **Constraints are never applied on `ephemeral` models or those materialized as `view`**. Only `table` and `incremental` models support applying and enforcing constraints.
 
+<VersionBlock lastVersion="1.8">
+
 ## Defining constraints
 
 Constraints may be defined for a single column, or at the model level for one or more columns. As a general rule, we recommend defining single-column constraints directly on those columns.
@@ -23,14 +25,10 @@ The structure of a constraint is:
 - `name` (optional): Human-friendly name for this constraint. Supported by some data platforms.
 - `columns` (model-level only): List of column names to apply the constraint over
 
-<VersionBlock lastVersion="1.8">
-
 When using `foreign_key`, you need to specify the referenced table's schema manually. Use `{{ target.schema }}` in the `expression` field to automatically pass the schema used by the target environment. Note that later versions of dbt will have more efficient ways of handling this. 
 
 For example: `expression: "{{ target.schema }}.customers(customer_id)"`
 
-</VersionBlock>
-
 <File name='models/schema.yml'>
 
 ```yml
@@ -68,9 +66,81 @@ models:
           - type: ...
 ```
 
+Today, in [dbt Cloud Versionless](/docs/dbt-versions/upgrade-dbt-version-in-cloud#versionless), you can use the new recommended syntax for defining foreign keys. This syntax leverages `ref`. For more information, refer to the section for the [forthcoming v1.9 release](/reference/resource-properties/constraints#whats-better-about-this-syntax).
+
+</File>
+
+</VersionBlock>
+
+<VersionBlock firstVersion="1.9">
+
+## Defining constraints
+
+Constraints may be defined for a single column, or at the model level for one or more columns. As a general rule, we recommend defining single-column constraints directly on those columns.
+
+If you are defining multiple `primary_key` constraints for a single model, those _must_ be defined at the model level. Defining multiple `primary_key` constraints at the column level is not supported. 
+
+The structure of a constraint is:
+- `type` (required): one of `not_null`, `unique`, `primary_key`, `foreign_key`, `check`, `custom`
+- `expression`: Free text input to qualify the constraint. Required for certain constraint types, and optional for others.
+- `name` (optional): Human-friendly name for this constraint. Supported by some data platforms.
+- `columns` (model-level only): List of column names to apply the constraint over
+
+Today, in [dbt Cloud Versionless](/docs/dbt-versions/upgrade-dbt-version-in-cloud#versionless), you can use the new recommended syntax for defining foreign keys. This syntax leverages `ref`.
+
+### What's better about this syntax?
+
+dbt will automatically resolve references to other models so that these references:
+
+- It captures dependencies.
+- Works across environments.
+
+Here are two examples demonstrating how the new syntax is utilized:
+
+<File name='models/schema.yml'>
+
+```yml
+
+models:
+  - name: my_model
+    constraints:
+      - type: foreign_key
+        columns: [id]
+        to: ref('my_model_to') | source('source', 'source_table')
+        to_columns: [id]
+    columns:
+      - name: id
+        data_type: integer
+
+```
+
 </File>
 
+<File name='models/schema.yml'>
+
+```yml
 
+models:
+  - name: my_model
+    columns:
+      - name: id
+        data_type: integer
+        constraints:
+        - type: foreign_key
+          to: ref('my_model_to') | source('source', 'source_table')
+          to_columns: [id]
+
+```
+
+</File>
+
+:::info
+
+The recommended syntax for defining foreign keys will be included in dbt Core v1.9 (open source) when it is released.
+
+:::
+
+</VersionBlock>
 
 ## Platform-specific support