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 allowed predicates in the current schema, their ids, and their expected object data type.
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. Once we have this defined, we should check for existing duplicates of this entity in the graph.
name = "John Doe"
is_a = "0c4e6054-5fd8-48a8-817c-f6611278f755" # Person Template Entity Id
ceo_of = "6086ed2c-3e45-4480-8ad6-aced06fac6fd" # Golden Entity ID
email_address = "[email protected]"
citation_urls = ["https://golden.com/wiki/johndoe"]
Calling the disambiguation function is necessary to create the entity in the next step, as the disambiguationCallId is required in the
CreateEntityInput object.john_doe_input = [
{
'Name': name,
'Is a': is_a,
'CEO of': ceo_of,
'Email Address': email_address,
}
]
response = goldapi.disambiguate_triples(twitter_example[0], with_diff=False)
disambiguationCallId = response['data']['disambiguateTriples']['disambiguationCallId']
response
{
'data': {
'disambiguateTriples':
{
'errors': None,
'disambiguationCallId': 'dcca2e44-8d9e-4edc-bcb6-48bb5fafc6bb',
'entities': []
}
}
}
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,
disambiguation_call_id=disambiguationCallId
)
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
{'data': {'createEntity': {'entity': {'__typename': 'Entity',
'id': 'b58235c8-fdcf-4bc9-a6dc-e1749edc4a4f',
'pathname': '/entity/b58235c8-fdcf-4bc9-a6dc-e1749edc4a4f',
'name': 'John Doe',
'description': None,
'thumbnail': None,
'goldenId': None,
'isA': {'nodes': [{'id': '0c4e6054-5fd8-48a8-817c-f6611278f755',
'name': 'Person'}]},
'statementsBySubjectId': {'nodes': [{'__typename': 'Statement',
'id': '1d4175cc-9390-4a78-bc6d-e5d09abd1562',
'dateAccepted': None,
'dateRejected': None,
'userId': '0xb5c46393798dA8f4853BF9028d5c3F63C1a64EC8',
'validationStatus': 'PENDING',
'subject': {'id': 'b58235c8-fdcf-4bc9-a6dc-e1749edc4a4f',
'pathname': '/entity/b58235c8-fdcf-4bc9-a6dc-e1749edc4a4f',
'name': 'John Doe',
'thumbnail': None},
'predicate': {'id': '94a8d215-ce32-4379-b18e-2aebf0794882',
'name': 'Is a',
'description': '',
'label': 'The entity type of this entity',
'objectType': 'ENTITY',
'showInInfobox': True},
'objectValue': None,
'objectEntity': {'id': '0c4e6054-5fd8-48a8-817c-f6611278f755',
'pathname': '/entity-type/0c4e6054-5fd8-48a8-817c-f6611278f755',
'name': 'Person',
'thumbnail': None},
'citationsByTripleId': {'nodes': []},
'qualifiersBySubjectId': {'nodes': []}},
{'__typename': 'Statement',
'id': '3be03c2a-0e69-43a6-a606-70f6dd60925e',
'dateAccepted': None,
'dateRejected': None,
'userId': '0xb5c46393798dA8f4853BF9028d5c3F63C1a64EC8',
'validationStatus': 'PENDING',
'subject': {'id': 'b58235c8-fdcf-4bc9-a6dc-e1749edc4a4f',
'pathname': '/entity/b58235c8-fdcf-4bc9-a6dc-e1749edc4a4f',
'name': 'John Doe',
'thumbnail': None},
'predicate': {'id': '3104de39-071c-47b8-86b4-d62ccc4a4fa6',
'name': 'CEO of',
'description': 'The organization this individual is charged with the management of – especially an independent legal entity such as a company or nonprofit institution. The CEO of an organization typically reports to the board of directors.',
'label': 'Organization this person is CEO of.',
'objectType': 'ENTITY',
'showInInfobox': True},
'objectValue': None,
'objectEntity': {'id': '6086ed2c-3e45-4480-8ad6-aced06fac6fd',
'pathname': '/entity/6086ed2c-3e45-4480-8ad6-aced06fac6fd',
'name': 'Golden',
'thumbnail': 'https://golden-media.s3.amazonaws.com/topics/5253ceef-b9f0-49c5-ae0e-e6a445078551.png'},
'citationsByTripleId': {'nodes': []},
'qualifiersBySubjectId': {'nodes': []}},
{'__typename': 'Statement',
'id': 'beaf1542-041c-48af-af0f-dcec31e975f4',
'dateAccepted': None,
'dateRejected': None,
'userId': '0xb5c46393798dA8f4853BF9028d5c3F63C1a64EC8',
'validationStatus': 'PENDING',
'subject': {'id': 'b58235c8-fdcf-4bc9-a6dc-e1749edc4a4f',
'pathname': '/entity/b58235c8-fdcf-4bc9-a6dc-e1749edc4a4f',
'name': 'John Doe',
'thumbnail': None},
'predicate': {'id': '0efd0441-1ffc-4e30-8806-e58c434770c8',
'name': 'Email Address',
'description': 'The email address associated with this entity that is 1. public (it is openly known the entity is associated with this email address) and 2. official (the entity has formally associated themselves with this phone number by posting it on a website, social media link, etc. that they are in control of).',
'label': 'Email address associated with an entity.',
'objectType': 'STRING',
'showInInfobox': True},
'objectValue': '[email protected]',
'objectEntity': None,
'citationsByTripleId': {'nodes': []},
'qualifiersBySubjectId': {'nodes': []}},
{'__typename': 'Statement',
'id': 'c1accc97-46c2-454a-b8c7-1b9b37a9e424',
'dateAccepted': None,
'dateRejected': None,
'userId': '0xb5c46393798dA8f4853BF9028d5c3F63C1a64EC8',
'validationStatus': 'PENDING',
'subject': {'id': 'b58235c8-fdcf-4bc9-a6dc-e1749edc4a4f',
'pathname': '/entity/b58235c8-fdcf-4bc9-a6dc-e1749edc4a4f',
'name': 'John Doe',
'thumbnail': None},
'predicate': {'id': 'a27218b8-6a4d-47bb-95b6-5a55334fac1c',
'name': 'Name',
'description': '',
'label': 'The primary name associated with this entity',
'objectType': 'STRING',
'showInInfobox': False},
'objectValue': 'John Doe',
'objectEntity': None,
'citationsByTripleId': {'nodes': []},
'qualifiersBySubjectId': {'nodes': []}}]}}}}
}
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
Last modified 2mo ago