mirror of
https://github.com/datahub-project/datahub.git
synced 2025-10-18 12:27:15 +00:00
docs: update graphql docs on forms & structured properties (#11100)
This commit is contained in:
Hyejin Yoon
GitHub
parent
8bea5d2a3d
commit
40e61f9d6e
@ -9,16 +9,16 @@ Documentation Forms are a way for end-users to fill out all mandatory attributes
|
||||
|
||||
Learn more about forms in the [Documentation Forms Feature Guide](../../../docs/features/feature-guides/documentation-forms.md).
|
||||
|
||||
|
||||
### 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
|
||||
|
||||
For this tutorial, you need to deploy DataHub Quickstart and ingest sample data.
|
||||
For detailed information, please refer to [Datahub Quickstart Guide](/docs/quickstart.md).
|
||||
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
@ -29,14 +29,45 @@ Connect to your instance via [init](https://datahubproject.io/docs/cli/#init):
|
||||
2. Set the server to your sandbox instance, `https://{your-instance-address}/gms`
|
||||
3. Set the token to your access token
|
||||
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
|
||||
## Create a Form
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="graphQL" label="GraphQL">
|
||||
|
||||
```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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
Create a yaml file representing the forms you’d like to load.
|
||||
@ -111,8 +142,42 @@ If successful, you should see `Created form urn:li:form:...`
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Read Property Definition
|
||||
## Update Form
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="graphQL" label="GraphQL">
|
||||
|
||||
```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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Read Property Definition
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
@ -146,3 +211,60 @@ If successful, you should see metadata about your form returned like below.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Delete Form
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="graphQL" label="GraphQL">
|
||||
|
||||
```graphql
|
||||
mutation deleteForm {
|
||||
deleteForm(
|
||||
input: {
|
||||
urn: "urn:li:form:metadataInitiative2024"
|
||||
}
|
||||
)
|
||||
}
|
||||
```
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Assign Form to Entities
|
||||
|
||||
For assigning a form to a given list of entities:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="graphQL" label="GraphQL">
|
||||
|
||||
```graphql
|
||||
mutation batchAssignForm {
|
||||
batchAssignForm(
|
||||
input: {
|
||||
formUrn: "urn:li:form:myform",
|
||||
entityUrns: ["urn:li:dataset:mydataset1", "urn:li:dataset:mydataset2"]
|
||||
}
|
||||
)
|
||||
}
|
||||
```
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Remove Form from Entities
|
||||
|
||||
For removing a form from a given list of entities:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="graphQL" label="GraphQL">
|
||||
|
||||
```graphql
|
||||
mutation batchRemoveForm {
|
||||
batchRemoveForm(
|
||||
input: {
|
||||
formUrn: "urn:li:form:myform",
|
||||
entityUrns: ["urn:li:dataset:mydataset1", "urn:li:dataset:mydataset2"]
|
||||
}
|
||||
)
|
||||
}
|
||||
```
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
@ -56,7 +56,33 @@ Requirements for OpenAPI are:
|
||||
The following code will create a structured property `io.acryl.privacy.retentionTime`.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="CLI" label="CLI" default>
|
||||
<TabItem value="graphql" label="graphQL" default>
|
||||
|
||||
```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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
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,37 @@ Example Response:
|
||||
This action will set/replace all structured properties on the entity. See PATCH operations to add/remove a single property.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="CLI" label="CLI" default>
|
||||
<TabItem value="graphQL" label="GraphQL" default>
|
||||
|
||||
```graphql
|
||||
mutation upsertStructuredProperties {
|
||||
upsertStructuredProperties(
|
||||
input: {
|
||||
assetUrn: "urn:li:mydataset1",
|
||||
structuredPropertyInputParams: [
|
||||
{
|
||||
structuredPropertyUrn: "urn:li:structuredProperty:mystructuredproperty",
|
||||
values: [
|
||||
{
|
||||
stringValue: "123"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
) {
|
||||
properties {
|
||||
structuredProperty {
|
||||
urn
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="CLI" label="CLI">
|
||||
|
||||
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 +522,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:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="graphql" label="GraphQL" default>
|
||||
|
||||
```graphql
|
||||
mutation removeStructuredProperties {
|
||||
removeStructuredProperties(
|
||||
input: {
|
||||
assetUrn: "urn:li:mydataset1",
|
||||
structuredPropertyUrns: ["urn:li:structuredProperty:mystructuredproperty"]
|
||||
}
|
||||
) {
|
||||
properties {
|
||||
structuredProperty {urn}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## 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 +861,38 @@ 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.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="graphql" label="GraphQL">
|
||||
|
||||
```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: "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
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="OpenAPI v2" label="OpenAPI v2">
|
||||
|
||||
```shell
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user