Entities & Relationships
Entities are the building blocks of SixDegree's ontology. Learn what they are, how they're discovered, and how they relate to each other.
What is an Entity?
An entity represents a long-living resource in your organization—something that persists over time and can be identified, managed, and related to other resources:
- Code — repositories, organizations, projects
- Infrastructure — Kubernetes deployments, services, namespaces, Docker images
- Services — PagerDuty services, Argo CD applications
- Integrations — Snyk projects, Grafana dashboards, Slack channels
- People — users, teams, Okta groups
Entities are durable resources that exist until explicitly deleted. Ephemeral data like pull requests, commits, issues, incidents, and vulnerabilities are not stored as entities. Instead, this data is retrieved on-demand through tools that operate on entities.
For example, a GitHubRepository is an entity, but its pull requests and commits are retrieved via tools like github.getPullRequests(repo).
Each entity has:
- A type that defines what kind of thing it is (e.g.,
GithubRepository,KubernetesDeployment) - Attributes containing properties specific to that entity
- Relationships connecting it to other entities in your ontology
Entity Structure
Entities follow a Kubernetes-inspired structure with group, version, and kind:
entities.sixdegree.ai/v1/GithubRepository
└── group ──────────┘ └┘ └── kind ────────┘
└── version
This fully-qualified type ensures entities from different sources never collide, even if they share a name.
Entity Attributes
Each entity has universal attributes that are always present:
| Attribute | Description |
|---|---|
| UID | Unique identifier |
| Name | Human-readable name |
| Kind | Entity type (e.g., GithubRepository) |
| Namespace | Logical grouping within an environment |
| Labels | Key-value pairs for filtering and organization |
| Annotations | Key-value pairs for metadata |
Entities also have type-specific attributes in their spec:
- Repositories: URL, primary language, description, star count, fork count, visibility
- Docker images: tags, digest, size, build timestamp, OS, architecture
- Users: email, profile picture, role, company
- Kubernetes resources: cluster, namespace, labels, status, replicas
Relationships
Relationships connect entities to each other, creating the ontology graph. Each relationship has a type that describes the connection:
| Relationship Type | Example |
|---|---|
| Ownership | Organization OWNS Repository |
| Contribution | User CONTRIBUTES_TO Repository |
| Membership | User MEMBER_OF Organization |
| Deployment | ArgoApplication DEPLOYS Repository |
| Build | Repository BUILT_INTO DockerImage |
| Hierarchy | Dashboard IN_FOLDER Folder |
| Custom | Molecules can define domain-specific relationship types |
Relationships can also carry their own attributes (labels, annotations, spec) and optional weights for graph algorithms like PageRank and shortest path.
Entity Discovery
Entities are discovered automatically through molecules (discovery plugins):
Discovery Process
- Configuration: You configure a molecule with credentials and settings
- Execution: The molecule scans the external service
- Entity extraction: The molecule identifies entities and their attributes
- Relationship mapping: The molecule determines how entities relate
- Graph update: Entities and relationships are added to your ontology
Discovery Scheduling
Discovery can run in different modes:
- Manual — triggered on-demand from the UI or API
- Polling — scheduled at intervals (e.g., every 15 minutes, hourly, daily)
- Webhook — real-time updates pushed from the external service
- Both — polling as a safety net with webhooks for real-time updates
Discovery Status
Each discovery run progresses through these states:
| State | Description | What to Do |
|---|---|---|
| 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 error details |
You can view discovery status and history for each molecule in the Integrations section of the UI.
Working with Entities
Browsing Entities
Use the ontology graph to explore entities visually, or list them by type:
curl https://api.sixdegree.ai/environments/{env-id}/entities?kind=GithubRepository
Querying Relationships
Find how entities connect using ontology queries:
MATCH (u:User)-[:CONTRIBUTES_TO]->(r:Repository)
WHERE u.name = "Alice"
RETURN r.name
Asking AI
The simplest way to explore entities is through natural language:
"What repositories does Alice contribute to?"
"Show me all services deployed from the api-service repo"
"Who owns the checkout microservice?"
Next Steps
- Ontology — Understanding the knowledge graph
- Tools — How AI retrieves ephemeral data and takes actions
- Molecules — How entities are discovered
- Exploring the Ontology — Navigate your entity graph