Create Entities
A short guide to adding Entities with Minimum Disambiguation Triples(MDTs) to the Golden decentralized knowledge graph using the godel SDK. Please see the Golden Protocol FAQ Guide and the Adding Structured Data Guide to learn more about Golden, data submission, and rewards.
Note: Attribution and eligibility for testnet points on triple submissions will be assigned by the earliest timestamped transaction.
This guide requires you install Godel's data-tools.
You can do this with
pip install godel[data-tools]. This comes pre-installed if using the godel docker image.Let's connect the python wrapper to the Golden GraphQL API.
Make sure you ran through the prerequisites for this guide and have learned to authenticate and retrieve your JWT token in Godel.
from godel import GoldenAPI
JWT_TOKEN = #YOUR_JWT_TOKEN_HERE
API_URL = "https://dapp.golden.xyz/graphql"
SANDBOX_URL = "https://sandbox.dapp.golden.xyz/graphql" # Use the sandbox API to test your submissions
goldapi = GoldenAPI(url=API_URL)
goldapi.set_jwt_token(jwt_token=JWT_TOKEN)
import pandas as pd
# Test with search
search_results = goldapi.entity_search(name="Miles")
search_results_df = pd.DataFrame(search_results["data"]["entityByName"]["nodes"])
search_results_df
Text | id | name | description | thumbnail | goldenId | pathname |
|---|---|---|---|---|---|---|
0 | d95ef4b0-e006-4203-bfb4-adbe99f63ce7 | Miles Wolff | Id nihil blanditiis eius fugit odit blanditiis... | https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHir... | None | /entity/d95ef4b0-e006-4203-bfb4-adbe99f63ce7 |
You can run the code below to get the list of accepted predicates into the knowledge graph, its data types, and submit templates for different kinds of entities.
import pandas as pd
predicates = {}
for p in goldapi.predicates()["data"]["predicates"]["edges"]:
p = p["node"]
predicates[p["name"]] = {"id": p["id"], "objectType": p["objectType"]}
predicates_df = pd.DataFrame(predicates).transpose()
predicates_df.head()
Text | id | objectType |
|---|---|---|
CEO | 0a87e996-34b4-46ba-909a-70ab67b1f811 | ENTITY |
Email address | 0efd0441-1ffc-4e30-8806-e58c434770c8 | STRING |
YouTube channel | 12acb8fe-0573-4ca8-8cc1-180cc6ba3486 | ANY_URI |
Total funding amount | 13a7e8b6-7270-4c99-81e9-9d752e0c295c | FLOAT |
Whitepaper | 14fa743c-8161-42e8-a92f-5c29c70e87f8 | ANY_URI |
templates = {}
for t in goldapi.templates()["data"]["templates"]["edges"]:
t = t["node"]
templates[t["entity"]["name"]] = {"id": t["id"], "entityId": t["entityId"], "entityDescription": t["entity"]["description"]}
templates_df = pd.DataFrame(templates).transpose()
templates_df
Text | id | entityId | entityDescription |
|---|---|---|---|
Person | 0dea0f27-ce0c-4b4f-8ddb-5ff6adb57e12 | 0c4e6054-5fd8-48a8-817c-f6611278f755 | None |
Company | 9553f193-a46a-4b46-9c0f-5287289644a6 | 0a9fcc89-e14b-47af-85c3-8465ca607c29 | None |
We need source data on the entity you would like to submit
name = "John Doe"
is_a = "0c4e6054-5fd8-48a8-817c-f6611278f755" # Person Template Entity Id
ceo_of = "20ab9281-fd5f-4717-ab73-ecd24fff66fe" # Huel and Sons Entity ID
email_address = "[email protected]"
citation_urls = ["https://golden.com/wiki/johndoe"]
We're going to create the
CreateEntityInput, which requires Minimum Disambiguated Triples (MDTs).MDTs are the required triples you must submit along with the entity you want to create.
This helps us with disambiguation, deduplication, and arbitrary entity submissions with zero triples.
from godel.schema import CreateEntityInput, StatementInputRecordInput
print(repr(CreateEntityInput))
StatementInputRecordInput
input CreateEntityInput {
clientMutationId: String
name: String!
statements: [StatementInputRecordInput]
}
input StatementInputRecordInput {
predicateId: UUID!
objectValue: String
objectEntityId: UUID
citationUrls: [String]
qualifiers: [QualifierInputRecordInput]
}
First, create your triples with the
StatementInputRecordInput's.You'll notice that the "CEO of" statement is commented out. Without this, even if you have the email address statement, you will not be able to submit the entity since it does not fulfill the MDTs required. We are using
pandas here to make working with data easier, but it is not a requirement.Remove the comment-out of the "CEO of" statement to successfully submit the entity.
# Create triples inputs
statements = []
# Add Template
statements.append(
StatementInputRecordInput(
predicate_id = predicates["Is a"]["id"],
object_entity_id = is_a,
citation_urls = [],
qualifiers = [],
)
)
# Add Name
statements.append(
StatementInputRecordInput(
predicate_id = predicates["Name"]["id"],
object_value = name,
citation_urls = [],
qualifiers = [],
)
)
# Add Email Address
statements.append(
StatementInputRecordInput(
predicate_id = predicates["Email address"]["id"],
object_value = email_address,
citation_urls = [],
qualifiers = [],
)
)
# Add CEO of
# statements.append(
# StatementInputRecordInput(
# predicate_id = predicates["CEO of"]["id"],
# object_entity_id = ceo_of,
# citation_urls = [],
# qualifiers = [],
# )
# )
Now that you have the statements, you can create your
CreateEntityInput.# Create Entity Input
create_entity_input = CreateEntityInput(
statements = statements
)
create_entity_input.__to_json_value__()
{'name': 'John Doe',
'statements': [{'predicateId': '94a8d215-ce32-4379-b18e-2aebf0794882',
'objectEntityId': '0c4e6054-5fd8-48a8-817c-f6611278f755',
'citationUrls': ['https://golden.com/wiki/johndoe'],
'qualifiers': []},
{'predicateId': '0efd0441-1ffc-4e30-8806-e58c434770c8',
'objectValue': '[email protected]',
'citationUrls': ['https://golden.com/wiki/johndoe'],
'qualifiers': []}]}
data = goldapi.create_entity(create_entity_input=create_entity_input)
data
GraphQL query failed with 1 errors
{'errors': [{'extensions': {'messages': [], 'exception': {}},
'message': 'All required statements must be provided:\n- entity type "person" must have a statement from at least one of these predicates: "website", "angelListUrl", "linkedInUrl", "founderOf", "ceoOf"',
'locations': [{'line': 2, 'column': 1}],
'path': ['createEntity'],
'stack': ['Error: All required statements must be provided:',
'- entity type "person" must have a statement from at least one of these predicates: "website", "angelListUrl", "linkedInUrl", "founderOf", "ceoOf"',
' at checkMinimumRequiredStatements (/home/andrew/golden/dapp/app/db/entityMinimumRequiredStatements.ts:74:11)',
' at createEntityWrapper (/home/andrew/golden/dapp/db/graphql/plugins/CreateEntityPlugin.server.ts:17:33)',
' at resolve (/home/andrew/golden/dapp/node_modules/graphile-utils/src/makeWrapResolversPlugin.ts:180:18)',
' at resolve (/home/andrew/golden/dapp/node_modules/@graphile/operation-hooks/lib/OperationHooksCorePlugin.js:122:38)',
' at runMicrotasks (<anonymous>)',
' at processTicksAndRejections (node:internal/process/task_queues:96:5)',
' at async /home/andrew/golden/dapp/node_modules/postgraphile/src/postgraphile/withPostGraphileContext.ts:227:16',
' at async withAuthenticatedPgClient (/home/andrew/golden/dapp/node_modules/postgraphile/src/postgraphile/withPostGraphileContext.ts:169:20)',
' at async /home/andrew/golden/dapp/node_modules/postgraphile/src/postgraphile/http/createPostGraphileHttpRequestHandler.ts:926:26',
' at async Promise.all (index 0)']}],
'data': {'createEntity': None}}
created_data_df = pd.DataFrame([data["data"]["createEntity"]["entity"]])
created_data_df
Text | __typename | id | pathname | name | description | thumbnail | goldenId | isA | statementsBySubjectId |
|---|---|---|---|---|---|---|---|---|---|
0 | Entity | 18998a05-d972-44cc-9d45-c75c9477c98d | /entity/18998a05-d972-44cc-9d45-c75c9477c98d | John Doe | None | None | None | {'nodes': [{'id': '0c4e6054-5fd8-48a8-817c-f66... | {'nodes': [{'__typename': 'Statement', 'id': '... |
created_entity_id = data["data"]["createEntity"]["entity"]["id"]
created_entity_id
link = f"https://dapp.golden.xyz/entity/{created_entity_id}"
link
'https://dapp.golden.xyz/entity/18998a05-d972-44cc-9d45-c75c9477c98d'
Last modified 2mo ago