Entities & Relationships
An entity is a durable, identifiable resource in your organization. It persists over time and can be connected to other resources in a graph.
What is an entity?
Entities represent the long-living objects that SixDegree discovers and tracks across your tools and infrastructure:
| Category | Examples |
|---|---|
| Revenue | Salesforce accounts, opportunities, Stripe subscriptions |
| Support | Zendesk tickets, Intercom conversations, PagerDuty services |
| Operations | NetSuite vendors, contracts, spend records |
| People | Users, teams, Okta groups |
| Engineering | Repositories, Kubernetes deployments, services |
Entities are durable resources that exist until explicitly deleted. Ephemeral data (open opportunities, ticket replies, incidents, invoices) is not stored as entities. It's retrieved on demand through tools that operate on entities.
A SalesforceAccount is an entity. Its open opportunities are fetched via salesforce_get_opportunities when the agent needs them.
Entity structure
Entities follow a Kubernetes-inspired fully-qualified type: group/version/kind.
entities.sixdegree.ai/v1/SalesforceAccount
└── group ──────────┘ └┘ └── kind ────────┘
└── version
This naming scheme ensures entities from different sources never collide, even when two systems use the same name for different concepts.
Universal attributes
Every entity, regardless of type, carries these fields:
| Attribute | Description |
|---|---|
uid | Unique identifier within the environment |
name | Human-readable display name |
kind | Entity type (e.g., SalesforceAccount) |
namespace | Logical grouping within an environment |
labels | Key-value pairs for filtering and organization |
annotations | Key-value pairs for arbitrary metadata |
Type-specific attributes
Each entity kind also carries a spec with fields specific to that type:
- Accounts: industry, ARR, renewal date, owner, health score, region
- Subscriptions: plan, seats, status, current period end, MRR
- Tickets: priority, status, requester, assignee, SLA target
- Users: email, profile picture, role, company
Labels and annotations on entities are indexed. Use them to filter large entity sets efficiently. For example, filter accounts by region label before running a graph query.
Canonical and native kinds
Every entity has a native kind that names exactly where it came from: GithubRepository, SalesforceAccount, WorkdayOrganization. Native kinds are faithful to the source system, which means the same real-world thing can show up under several of them. A single childcare center might exist as a Salesforce account, a Workday cost center, and a LineLeader site all at once.
A canonical kind unifies those native kinds into one type you can query directly. Querying the canonical Center reads across Salesforce, Workday, and LineLeader transparently and returns one entity per center, with a stable set of canonical attributes regardless of which source each value came from.
| Native kind | Canonical kind | |
|---|---|---|
| Names | One source system | A concept across many sources |
| Example | WorkdayOrganization, SalesforceAccount | Center, Person, Service |
| Attributes | The source's own field names | A stable, source-independent set |
| You use it for | Drilling into one system's data | Asking questions across systems |
Canonical attributes are projected at query time. When you read a canonical entity, the underlying native fields remain available for drill-down, so you never lose the source detail. Which native kinds roll up into a canonical kind, and how their fields map, is declared by the integration that owns the vertical.
When two sources offer a value for the same canonical attribute, a declared precedence rule picks the authoritative one and records the other as provenance, so you can always trace which source a value came from. Canonical relationships are traversable too: the platform materializes the edges between canonical entities, so you can walk from one canonical kind to another without knowing which native systems back each side.
Use describe_entity_type on a canonical kind to see its canonical attributes and which native kind each one resolves from. It's the contract the agent grounds on before it queries.
Relationships
Relationships connect entities to form the ontology graph. Each relationship has a typed direction and can carry its own attributes, labels, and optional weights for graph algorithms like PageRank and shortest path.
| Relationship type | Example |
|---|---|
OWNS | Person owns Account |
RENEWS | Subscription renews Account |
ESCALATED_TO | Ticket escalated to Incident |
AFFECTS | Incident affects Account |
BELONGS_TO | Contract belongs to Vendor |
DEPENDS_ON | Service depends on Service |
| Custom | Molecules can define domain-specific relationship types |
Entity discovery
Entities are discovered automatically through molecules: the discovery and integration plugins that connect SixDegree to external services.
Discovery process
- You configure a molecule with credentials and settings.
- The molecule scans the external service on its schedule.
- It identifies entities and their attributes.
- It maps relationships between entities.
- Entities and relationships are written to your ontology graph.
Discovery modes
| Mode | How it works | Best for |
|---|---|---|
| Manual | Triggered on-demand from the UI or API | One-off refreshes, testing |
| Polling | Runs on a fixed interval (e.g., every 15 minutes) | Services without webhook support |
| Webhook | Real-time updates pushed from the external service | Low-latency freshness |
| Polling + Webhook | Webhook for speed, polling as a safety net | Production environments |
Discovery run states
| State | Meaning | Action |
|---|---|---|
Pending | Scheduled but not yet started | Wait for the run to begin |
Running | Actively scanning the external service | Monitor progress in the UI |
Completed | Finished successfully | Review discovered entities in the ontology |
Failed | Encountered errors | Check molecule logs for details |
If discovery fails repeatedly, entities from the last successful run remain in the graph but may no longer reflect the current state of the external system. Check molecule logs and credential validity when a molecule shows sustained failures.
You can view discovery status and history for each molecule in the Integrations section of the UI.
Working with entities
Browsing entities
The Ontology tab is the primary way to explore entities. Click any node in the graph or use the list view to filter by type. Selecting an entity opens a detail panel showing its attributes, relationships, and last-discovered time.
Screenshot needed: Entity list view: filterable table of entities for one type (e.g. SalesforceAccount), with columns for name, namespace, key attributes, last-updated, and a row click that opens the detail panel.
:::
You can also list entities by type directly from the API:
curl https://api.sixdegree.ai/environments/{env-id}/entities?kind=SalesforceAccount
Querying relationships
Traverse the ontology graph with a structured query that names a starting set and a relationship to follow:
{
"from": { "kind": "entities.sixdegree.ai/v1/SalesforceAccount", "name": "Acme" },
"traverse": [
{ "relation": "OWNS", "kind": "entities.sixdegree.ai/v1/SalesforceOpportunity" }
],
"select": { "mode": "entities", "fields": ["name"] }
}
The same structured form supports counts, classification, and cross-tabs. Most of the time you'll let the agent build these queries for you from a plain-language question.
Asking the agent
The agent understands your ontology and can answer questions in natural language:
"Which accounts renew in the next 30 days and have an open support escalation?"
"Show every touchpoint for this account: tickets, calls, and product usage"
"Which vendors are we paying for that no team used this quarter?"
"What depends on the payments service, and who owns it?"
The agent resolves these questions by searching entities, traversing relationships, and fetching ephemeral data through tools as needed.
Next steps
- Ontology: how entities and relationships form a knowledge graph
- Querying the graph: how the engine answers questions over entities and relationships
- Tools: how the agent retrieves ephemeral data and takes actions on entities
- Molecules: how entities are discovered from external services
- Exploring the Ontology: navigate your entity graph in the UI
- Agent: how the agent uses entities to answer questions and take action