From 4f1287de7be79e5b91498b6dc28d7eaecc9c3116 Mon Sep 17 00:00:00 2001
From: yoonhyejin <0327jane@gmail.com>
Date: Tue, 6 Aug 2024 15:44:14 +0900
Subject: [PATCH] feat: add graphql docs on forms & structured properties
---
docs/api/tutorials/forms.md | 129 +++++++++++++++++-
docs/api/tutorials/structured-properties.md | 98 ++++++++++++-
.../feature-guides/documentation-forms.md | 2 +-
3 files changed, 224 insertions(+), 5 deletions(-)
diff --git a/docs/api/tutorials/forms.md b/docs/api/tutorials/forms.md
index 3f28353595be7..49a61045cc1f9 100644
--- a/docs/api/tutorials/forms.md
+++ b/docs/api/tutorials/forms.md
@@ -11,7 +11,9 @@ Learn more about forms in the [Documentation Forms Feature Guide](../../../docs/
### Goal Of This Guide
-This guide will show you how to create and read forms.
+This guide will show you how to
+- Create, Update, Read, and Delete a form
+- Assign and Remove a form from entities
## Prerequisites
@@ -37,6 +39,39 @@ Connect to your instance via [init](https://datahubproject.io/docs/cli/#init):
## Create a Form
+
+
+```graphql
+mutation createForm {
+ createForm(
+ input: {
+ id: "metadataInitiative2024",
+ name: "Metadata Initiative 2024",
+ description: "How we want to ensure the most important data assets in our organization have all of the most important and expected pieces of metadata filled out",
+ type: VERIFICATION,
+ prompts: [
+ {
+ id: "123",
+ title: "retentionTime",
+ description: "Apply Retention Time structured property to form",
+ type: STRUCTURED_PROPERTY,
+ structuredPropertyParams: {
+ urn: "urn:li:structuredProperty:retentionTime"
+ }
+ }
+ ],
+ actors: {
+ users: ["urn:li:corpuser:jane@email.com", "urn:li:corpuser:john@email.com"],
+ groups: ["urn:li:corpGroup:team@email.com"]
+ }
+ }
+ ) {
+ urn
+ }
+}
+```
+
+
Create a yaml file representing the forms you’d like to load.
@@ -111,8 +146,42 @@ If successful, you should see `Created form urn:li:form:...`
-## Read Property Definition
+## Update Form
+
+
+
+
+```graphql
+mutation updateForm {
+ updateForm(
+ input: {
+ urn: "urn:li:form:metadataInitiative2024",
+ name: "Metadata Initiative 2024",
+ description: "How we want to ensure the most important data assets in our organization have all of the most important and expected pieces of metadata filled out",
+ type: VERIFICATION,
+ promptsToAdd: [
+ {
+ id: "456",
+ title: "deprecationDate",
+ description: "Deprecation date for dataset",
+ type: STRUCTURED_PROPERTY,
+ structuredPropertyParams: {
+ urn: "urn:li:structuredProperty:deprecationDate"
+ }
+ }
+ ]
+ promptsToRemove: ["123"]
+ }
+ ) {
+ urn
+ }
+}
+```
+
+
+
+## Read Property Definition
@@ -146,3 +215,59 @@ If successful, you should see metadata about your form returned like below.
+
+## Delete Form
+
+
+
+
+```graphql
+mutation deleteForm {
+ deleteForm(
+ input: {
+ urn: "urn:li:form:metadataInitiative2024"
+ }
+ )
+}
+```
+
+
+
+## Assign Form to Entities
+
+For assigning a form to a given list of entities:
+
+
+
+
+```graphql
+mutation batchAssignForm {
+ batchAssignForm(
+ input: {
+ formUrn: "urn:li:form:myform",
+ entityUrns: ["urn:li:dataset:mydataset1", "urn:li:dataset:mydataset2"]
+ }
+ )
+}
+```
+
+
+
+## Remove Form from Entities
+
+For removing a form from a given list of entities:
+
+
+
+
+```graphql
+ batchRemoveForm(
+ input: {
+ formUrn: "urn:li:form:myform",
+ entityUrns: ["urn:li:dataset:mydataset1", "urn:li:dataset:mydataset2"]
+ }
+ )
+}
+```
+
+
diff --git a/docs/api/tutorials/structured-properties.md b/docs/api/tutorials/structured-properties.md
index c56a2848638fc..1d1ef3d74016c 100644
--- a/docs/api/tutorials/structured-properties.md
+++ b/docs/api/tutorials/structured-properties.md
@@ -56,7 +56,33 @@ Requirements for OpenAPI are:
The following code will create a structured property `io.acryl.privacy.retentionTime`.
-
+
+
+```graphql
+mutation createStructuredProperty {
+ createStructuredProperty(
+ input: {
+ id: "retentionTime",
+ qualifiedName:"retentionTime",
+ displayName: "Retention Time",
+ description: "Retention Time is used to figure out how long to retain records in a dataset",
+ valueType: "urn:li:dataType:number",
+ allowedValues: [
+ {numberValue: 30, description: "30 days, usually reserved for datasets that are ephemeral and contain pii"},
+ {numberValue: 90, description:"description: Use this for datasets that drive monthly reporting but contain pii"},
+ {numberValue: 365, description:"Use this for non-sensitive data that can be retained for longer"}
+ ],
+ cardinality: SINGLE,
+ entityTypes: ["urn:li:entityType:dataset", "urn:li:entityType:dataFlow"],
+ }
+ ) {
+ urn
+ }
+}
+```
+
+
+
Create a yaml file representing the properties you’d like to load.
For example, below file represents a property `io.acryl.privacy.retentionTime`. You can see the full example [here](https://github.com/datahub-project/datahub/blob/example-yaml-sp/metadata-ingestion/examples/structured_properties/struct_props.yaml).
@@ -355,7 +381,28 @@ Example Response:
This action will set/replace all structured properties on the entity. See PATCH operations to add/remove a single property.
-
+
+
+```graphql
+mutation upsertStructuredProperties {
+ upsertStructuredProperties(
+ input: {
+ assetUrn: "urn:li:mydataset1",
+ structuredPropertyInputParams: [{
+ structuredPropertyUrn: "urn:li:structuredProperty:mystructuredproperty",
+ values: [{stringValue: "123"}]
+ }]
+ }
+ ) {
+ properties {
+ structuredProperty {urn}
+ }
+ }
+}
+```
+
+
+
You can set structured properties to a dataset by creating a dataset yaml file with structured properties. For example, below is a dataset yaml file with structured properties in both the field and dataset level.
@@ -466,6 +513,31 @@ Or you can run the following command to view the properties associated with the
datahub dataset get --urn {urn}
```
+## Remove Structured Properties From a Dataset
+
+For removing a structured property or list of structured properties from a dataset:
+
+
+
+
+```graphql
+mutation removeStructuredProperties {
+ removeStructuredProperties(
+ input: {
+ assetUrn: "urn:li:mydataset1",
+ structuredPropertyUrns: ["urn:li:structuredProperty:mystructuredproperty"]
+ }
+ ) {
+ properties {
+ structuredProperty {urn}
+ }
+ }
+}
+```
+
+
+
+
## Patch Structured Property Value
This section will show you how to patch a structured property value - either by removing, adding, or upserting a single property.
@@ -780,6 +852,28 @@ You can see that the first property has been removed and the second property is
In this example, we'll add the property back with a different value, preserving the existing property.
+
+
+```graphql
+mutation updateStructuredProperty {
+ updateStructuredProperty(
+ input: {
+ urn:"urn:li:structuredProperty:retentionTime"
+ displayName: "Retention Time",
+ description: "Retention Time is used to figure out how long to retain records in a dataset",
+ newAllowedValues: [
+ {numberValue: 30, description: "30 days, usually reserved for datasets that are ephemeral and contain pii"},
+ {numberValue: 90, description:"description: Use this for datasets that drive monthly reporting but contain pii"},
+ {numberValue: 365, description:"Use this for non-sensitive data that can be retained for longer"}
+ ],
+ }
+ ) {
+ urn
+ }
+}
+```
+
+
```shell
diff --git a/docs/features/feature-guides/documentation-forms.md b/docs/features/feature-guides/documentation-forms.md
index b007892e66094..2edeb8ce302d7 100644
--- a/docs/features/feature-guides/documentation-forms.md
+++ b/docs/features/feature-guides/documentation-forms.md
@@ -101,7 +101,7 @@ You sure can! Please keep in mind that an Asset will only be considered Document
### API Tutorials
-- [Create a Documentation Form](../../../docs/api/tutorials/forms.md)
+- [API Guides on Documentation Form](../../../docs/api/tutorials/forms.md)
:::note
You must create a Structured Property before including it in a Documentation Form.