# Asset Tags

**Tags** are a powerful way to manage and search for [**floors**](https://docs.butlr.io/asset-management/graphql-api-overview/floors), [**rooms**](https://docs.butlr.io/asset-management/graphql-api-overview/rooms), and [**zones**](https://docs.butlr.io/asset-management/graphql-api-overview/zones). The GraphQL API allows you to assign, manage, and query tags, efficiently categorizing spaces and retrieving relevant data.

### **Use Cases for Tags**

* **Organizing Spaces:** Categorize rooms, floors, and zones (e.g., `meeting room`, `bathroom`, `kitchen`) for better management.
* **Simplifying Search:** Quickly locate assets by filtering tags like `conference room` or `workstation`.
* **Aggregating Data:** Group assets with shared tags (e.g., `windows`, `dual-monitor`) for detailed analysis.

<figure><img src="https://3289302098-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fe3YixUK5tCcflJxye0bT%2Fuploads%2Fgit-blob-c53031f49676555e1c590ca33627035126ec2bd5%2Ftag%20filter.png?alt=media" alt=""><figcaption></figcaption></figure>

### **Creating a Tag**

To create a new tag, use the `createTag` mutation. Tags are associated by their unique ID, allowing you to update tag names without affecting associations.

```graphql
mutation CreateTag($input: CreateTagInput!) {
  createTag(input: $input) {
    name
    id
  }
}

input CreateTagInput {
  name: String!
}
```

### **Associating a Tag**

After creating a tag, associate it with **Zones**, **Rooms**, or **Floors** using their IDs. Use the `associateTag` mutation to define these relationships.

<pre class="language-graphql"><code class="lang-graphql"><strong>mutation AssociateTag($input: AssociateTagInput!) {
</strong>  associateTag(input: $input) {
    tag {
      name
      id
    }
    zones {
      name
    }
    rooms {
      name
    }
    floors {
      name
    }
  }
}


input AssociateTagInput {
  # The list of ids to associate the tag with (any combination of floors/rooms/zones)
  ids: [String!]
  # The tag id
  tag_id: String!
}


</code></pre>

The `ids` field is an array of Rooms, Zones and Floors that you want to tag, for example:

```json
"ids": [
  "space_lvgwckxar9ddupm40768mkfq",
  "room_2mALGwh4NLWDyaY7ORteOICBNYK"
]
```

You can also disassociate a tag:

<pre class="language-graphql"><code class="lang-graphql"><strong>mutation DisassociateTag($input: DisassociateTagInput!) {
</strong>  disassociateTag(input: $input) {
    tag {
      name
      id
    }
    zones {
      name
    }
    rooms {
      name
    }
    floors {
      name
    }
  }
}


input DisassociateTagInput {
  # The list of ids to disassociate the tag with (any combination of floors/rooms/zones)
  ids: [String!]
  # The tag id
  tag_id: String!
}


</code></pre>

### **Querying by Tag**

Once tags are assigned, you can query for objects associated with specific tags, such as Floor, Rooms, or Zones.

```graphql
query ItemsFromTags($tagIds: [String!]!) {
  tags(ids: $tagIds) {
      id
      name
      floors {
        # full floor object – can pull any field normally on a floor
        id
        name
      }
      rooms {
        # full room object
        id
        name
      }
      zones {
        # full zone object
        id
        name
      }
    }
}
```

Or you can get information about associated Tags from a Floor, Room, or Zone object:

```graphql
query ItemsFromTags($tagIds: [String!]!) {
  floors {
    data {
      id
      name
      tags {
        id
        name
      }
    }
  }
}
```

### **Accessing Tag Details**

Tags are accessible as objects containing a `name` and an `id`. From a tag object, you can retrieve the associated Zones, Rooms, and Floors.

### **Query for Tags**

Retrieve all tags in your organization:

```graphql
query Tags() {
  tags {
    id
    name
  }
}
```

{% hint style="danger" %}
**Tag History Not Supported:**\
Our system currently does not retain a history of tag changes.\
For example, if Zones 1–5 are tagged as "Marketing" in September and updated to "Finance" in December, the original tag ("Marketing") will no longer be available for queries. Only the current tag assignment ("Finance") can be queried. Historical comparisons or analyses based on previous tags must be managed outside the system.\
\
\&#xNAN;*We plan to extend tagging to additional assets (e.g., site, building, sensor, hive) in the near future to enhance its capabilities further.*
{% endhint %}