Object Management

Creating, updating, and deleting objects in Infrahub

Objects are the fundamental data entities in Infrahub. This guide shows you how to create, update, and delete objects using the UI, GraphQL API, or Python SDK.

Creating Objects

You can create objects in three ways: through the UI, GraphQL mutations, or the Python SDK.

UI

1. Navigate to the object type in the sidebar (e.g., Devices, Locations)
2. Click Add [Object Type]
3. Fill in the required attributes
4. Set relationships by selecting existing objects
5. Click Save

The UI validates required fields and shows errors before allowing you to save.

GraphQL

Use the auto-generated mutation for your object type. The pattern is [ObjectKind]Create:

mutation {
  InfraDeviceCreate(
    data: {
      name: { value: "edge-router-01" }
      description: { value: "Edge router for datacenter" }
      status: { id: "<status-uuid>" }
      site: { id: "<site-uuid>" }
      device_type: { id: "<device-type-uuid>" }
    }
  ) {
    ok
    object {
      id
      display_label
    }
  }
}

Attributes use { value: "..." } syntax. Relationships use { id: "uuid" } or { hfid: ["identifier"] } syntax.

Python SDK

from infrahub_sdk import InfrahubClient

client = InfrahubClient()

# Create a new device
device = await client.create(
    kind="InfraDevice",
    name="edge-router-01",
    description="Edge router for datacenter",
    status="<status-uuid>",
    site="<site-uuid>",
    device_type="<device-type-uuid>"
)
await device.save()

print(f"Created device: {device.id}")

The SDK handles attribute and relationship serialization automatically.

Updating Objects

Update existing objects by modifying their attributes or relationships.

UI

1. Navigate to the object’s detail page
2. Click Edit or click directly on editable fields
3. Modify the values
4. Click Save

Changes are tracked in the activity feed and can be reverted using branches.

GraphQL

Use the [ObjectKind]Update mutation with the object’s ID:

mutation {
  InfraDeviceUpdate(
    data: {
      id: "<device-uuid>"
      description: { value: "Updated description" }
      status: { id: "<new-status-uuid>" }
    }
  ) {
    ok
    object {
      id
      description {
        value
      }
    }
  }
}

Only include the fields you want to change. Omitted fields remain unchanged.

Python SDK

from infrahub_sdk import InfrahubClient

client = InfrahubClient()

# Fetch the existing device
device = await client.get(kind="InfraDevice", id="<device-uuid>")

# Update attributes
device.description.value = "Updated description"
device.status.id = "<new-status-uuid>"

# Save changes
await device.save()

The SDK tracks which fields changed and only sends modified data.

Deleting Objects

Delete objects when they are no longer needed. Deletion is subject to relationship constraints.

UI

1. Navigate to the object’s detail page
2. Click the More actions menu (three dots)
3. Select Delete
4. Confirm the deletion

If the object has required relationships pointing to it, deletion will fail with an error message.

GraphQL

Use the [ObjectKind]Delete mutation:

mutation {
  InfraDeviceDelete(
    data: {
      id: "<device-uuid>"
    }
  ) {
    ok
  }
}

The mutation returns ok: false if deletion fails due to constraints.

Python SDK

from infrahub_sdk import InfrahubClient

client = InfrahubClient()

# Fetch and delete
device = await client.get(kind="InfraDevice", id="<device-uuid>")
await device.delete()

The SDK raises an exception if deletion fails.

Working with Attributes

Attributes hold data values and support metadata like source tracking and validation.

Setting Attribute Sources

You can specify where attribute values come from (e.g., a Profile or template):

mutation {
  InfraDeviceUpdate(
    data: {
      id: "<device-uuid>"
      description: {
        value: "From template"
        source: "<template-uuid>"
        is_from_profile: false
      }
    }
  ) {
    ok
  }
}

The source field tracks provenance, while is_from_profile indicates if the value comes from a Profile.

Attribute Flags

• is_default: True if using the schema’s default value
• is_from_profile: True if value comes from a Profile
• is_protected: Prevents modification
• is_visible: Controls UI visibility

Working with Relationships

Cardinality ONE

For single-value relationships, use { id: "uuid" }:

device_type: { id: "<device-type-uuid>" }

Cardinality MANY

For multi-value relationships, provide an array:

tags: [
  { id: "<tag-1-uuid>" },
  { id: "<tag-2-uuid>" }
]

Using Human-Friendly Identifiers (HFID)

Instead of UUIDs, you can use HFIDs:

site: { hfid: ["atl1"] }

HFIDs are auto-generated from key attributes and are more readable than UUIDs.

Batch Operations

Create multiple objects efficiently using the SDK:

from infrahub_sdk import InfrahubClient

client = InfrahubClient()

devices = [
    {"name": "router-01", "site": "<site-uuid>"},
    {"name": "router-02", "site": "<site-uuid>"},
    {"name": "router-03", "site": "<site-uuid>"},
]

for device_data in devices:
    device = await client.create(kind="InfraDevice", **device_data)
    await device.save()

For larger datasets, consider using YAML import (see Data Import).

Validation and Constraints

Infrahub validates objects against schema constraints:

• Required attributes: Must have a value
• Unique attributes: Value must be unique across objects
• Regex patterns: String values must match patterns
• Min/max values: Numbers must be within range
• Relationship cardinality: ONE relationships require exactly one peer

Validation errors are returned in the mutation response:

{
  "ok": false,
  "errors": [
    {
      "message": "name is required",
      "path": ["name"]
    }
  ]
}

Next Steps

• Learn about Data Import for bulk loading
• Explore Groups for organizing objects
• Use Profiles to apply common settings