The OriginTrail Global Hackaton is now live! Build trusted AI on the DKG and qualify for $30 000 reward pool
Visit hackathon page
Edit

DKG Social Graph Query Guide

Hackathon Guide with examples on how to interact with the provided example Hackathon Social Graph

This is a comprehensive guide for querying social graph data (tweets, Reddit posts, TikTok videos, news articles, etc.) on the OriginTrail Decentralized Knowledge Graph using SPARQL. This guide covers JSON-LD data structures, example queries, and available MCP/API tools for builders and AI agents.

Server: https://euphoria.origin-trail.network

Table of Contents

  1. Understanding JSON-LD Data Structures

    • Data Types Overview

    • Creator-Static Structure

    • Creator-Temporal Structure

    • Post-Static Structure

    • Post-Temporal Structure

    • Topic-Static Structure

    • Topic-Temporal Structure

  2. Available Query Tools

    • MCP Tool (Model Context Protocol)

    • REST API

  3. SPARQL Query Examples by Data Type

    • Querying Creator-Static Data

    • Querying Creator-Temporal Data

    • Querying Post-Static Data

    • Querying Post-Temporal Data

    • Querying Topic-Static Data

    • Querying Topic-Temporal Data

  4. Advanced Query Scenarios

    • Scenario 1: Get Trending Topics with Engagement Metrics

    • Scenario 2: Find Most Engaging Content Types for a Topic

    • Scenario 3: Find Topics by Category

    • Scenario 4: Topic Sentiment Analysis Over Time

  5. Supported SPARQL Query Types

    • SELECT Queries

    • CONSTRUCT Queries

    • ASK Queries

    • DESCRIBE Queries

  6. Usage Examples

    • Example 1: cURL Request

    • Example 2: JavaScript/Node.js

    • Example 3: Python

  7. Security & Validation

  8. Error Handling

  9. Query Optimization Tips

  10. API Documentation

  11. Support & Resources

Understanding JSON-LD Data Structures

The DKG stores social media data as JSON-LD Knowledge Assets using standard vocabularies (Schema.org, FOAF, PROV, SIOC, SKOS). Data is organized into static (unchanging metadata) and temporal (time-series observations) formats.

Data Types Overview

Type
Static
Temporal
Description

Creator

Profile metadata

Follower counts, connections over time

Social media accounts and users

Post

Content, author, URL

Engagement metrics (views, likes, shares)

Social media posts, articles, videos

Topic

Name, identifiers

Rankings, sentiment, post counts

Trending topics and hashtags

Creator-Static Structure

Represents a social media account's core identity:

Creator-Temporal Structure

Captures time-series data about account activity and connections:

Post-Static Structure

Core metadata about a social media post:

Post-Temporal Structure

Engagement metrics tracked over time:

Topic-Static Structure

Basic topic information:

Topic-Temporal Structure

Topic trends, rankings, and sentiment over time:

Available Query Tools

1. MCP Tool (Model Context Protocol)

Connect to the MCP server to use the SPARQL query tool with your AI agent.

MCP Server URL: https://euphoria.origin-trail.network/mcp

Tool Name: dkg-sparql-query

Description: Execute SPARQL queries on the OriginTrail DKG to query social graph data. Supports read-only queries: SELECT, CONSTRUCT, ASK, and DESCRIBE.

Input Parameter:

  • query (string, required): SPARQL query to execute

MCP Configuration Example (for Adding the MCP server to Cursor, VS Code, etc.):

Response Format: Returns formatted markdown text with query results in JSON format:

✅ Query executed successfully

Results:

2. REST API

Use the HTTP endpoint directly for integrations with your DKG Edge Node agent via MCP tools, scripts, or applications.

Endpoint:

POST https://euphoria.origin-trail.network/dkg-sparql-query

Headers:

Content-Type: application/json

Request Body:

Response (Success):

Response (Error):

HTTP Status Codes:

  • 200 - Query executed successfully

  • 400 - Invalid query (validation error)

  • 500 - Server error during query execution

SPARQL Query Examples by Data Type

Querying Creator-Static Data

Retrieve social media account profile information:

Querying Creator-Temporal Data

Get account observations including followers, connections, and profile details:

Querying Post-Static Data

Retrieve social media posts with metadata:

Querying Post-Temporal Data

Get engagement metrics for posts over time:

Querying Topic-Static Data

Retrieve topic metadata and identifiers:

Querying Topic-Temporal Data

Get topic trends, rankings, and engagement data:

Advanced Query Scenarios

Scenario 1: Get Trending Topics with Engagement Metrics

Find top 10 trending topics with contributor counts, post volumes, and trend direction:

Use Case: Content strategists planning social media campaigns based on trending topics.

Scenario 2: Find Most Engaging Content Types for a Topic

Analyze which content types (tweets, videos, news) generate the most engagement:

Use Case: Marketers optimizing content format mix for specific topics.

Scenario 3: Find Topics by Category

Discover all topics in a specific category (e.g., gaming):

Use Case: Content curators building category-specific feeds.

Scenario 4: Topic Sentiment Analysis Over Time

Track sentiment changes for a topic correlated with events:

Use Case: Sentiment analysts tracking public opinion trends.

Supported SPARQL Query Types

The DKG SPARQL endpoint supports read-only query operations:

SELECT Queries

Retrieve specific data fields matching patterns.

Example - Get Top Posts:

Returns: Array of result bindings

CONSTRUCT Queries

Build new RDF graphs from query patterns.

Example - Extract Topic Network:

Returns: RDF triples as N-Triples string

ASK Queries

Boolean pattern existence checks.

Example - Check if Topic Exists:

Returns: Boolean

DESCRIBE Queries

Retrieve all triples about a resource.

Example - Get Complete Topic Info:

Returns: All predicates and objects for the subject

Security & Validation

Allowed Operations

✅ SELECT - Query and retrieve data ✅ CONSTRUCT - Generate RDF graphs ✅ ASK - Boolean pattern matching ✅ DESCRIBE - Resource description

Blocked Operations

❌ INSERT - Write operations not permitted ❌ DELETE - Write operations not permitted ❌ UPDATE - Modification operations not permitted

Validation Rules

  • Query cannot be empty

  • Must be valid SPARQL syntax

  • SELECT and CONSTRUCT queries require WHERE clauses

  • Only read-only query types accepted

Usage Examples

Example 1: cURL Request - Query Trending Topics

Example 2: JavaScript/Node.js - Find Posts by Topic

Example 3: Python - Analyze Content Type Performance

Error Handling

Validation Errors (HTTP 400)

Empty Query:

Missing WHERE Clause:

Write Operation Blocked:

Execution Errors (HTTP 500)

Single Node Error:

Both Nodes Failed:

Query Optimization Tips

  1. Use LIMIT clauses - Prevent retrieving large datasets

  2. Filter early - Apply FILTER conditions to reduce data processing

  3. Be specific with properties - Query only the fields you need

  4. Use OPTIONAL wisely - Avoid excessive OPTIONAL clauses that slow queries

  5. Leverage aggregations - Use GROUP BY with aggregate functions for analytics

  6. Use prefixes - Make queries more readable and maintainable

  7. Filter by date ranges - Restrict temporal queries to relevant time periods

  8. Use specific URIs when known - Direct URI references are faster than patterns

API Documentation

Interactive API documentation is available via Swagger UI:

Swagger URL: https://euphoria.origin-trail.network/swagger

Browse all available endpoints, test queries interactively, and view detailed schemas.

Support & Resources

PreviousHackathon: Scaling Trust in the Age of AINextDelegated staking

Last updated

Was this helpful?