# Querying

The Query API is powerful tool used to find any "thing" in-game, providing a wide array of filters that can be used to isolate the entity you are searching for. Queries are highly optimized, and results are evaluated lazily, so query builders can be re-used.

There are many kinds of query builders, each of which way may have filters to make identifying entities easier. Here are the main types (and their inheritance structure):

* [InteractableQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/InteractableQueryBuilder.html)
  * [LocatableEntityQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/LocatableEntityQueryBuilder.html)
    * [RotatableQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/RotatableQueryBuilder.html)
      * [ActorQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/ActorQueryBuilder.html)
        * [NpcQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/NpcQueryBuilder.html)
        * [PlayerQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/PlayerQueryBuilder.html)
    * [BankQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/BankQueryBuilder.html)
    * [DepositBoxQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/DepositBoxQueryBuilder.html)
    * [GameObjectQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/GameObjectQueryBuilder.html)
    * [GroundItemQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/GroundItemQueryBuilder.html)
    * [ProjectileQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/ProjectileQueryBuilder.html)
    * [SpotAnimationQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/SpotAnimationQueryBuilder.html)
  * [SpriteItemQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/SpriteItemQueryBuilder.html)
  * [InterfaceComponentQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/InterfaceComponentQueryBuilder.html)
* [WorldQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/WorldQueryBuilder.html)
* [ChatboxQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/ChatboxQueryBuilder.html)
* [GrandExchangeQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/GrandExchangeQueryBuilder.html)
* [HintArrowQueryBuilder](https://runemate.gitlab.io/community/runemate-game-api/runemate-game-api/com/runemate/game/api/hybrid/queries/HintArrowQueryBuilder.html)

### Query Builder Types

There are several types of QueryBuilder, the most commonly used ones are covered below:

{% tabs %}
{% tab title="Items" %}
The **SpriteItemQueryBuilder** is used to search for items contained with InterfaceComponents, such as in the inventory, equipment or bank.

Depending on the origin of the item you are searching for, a SpriteItemQueryBuilder can be created using one of the following:

```java
//Inventory items
Inventory.newQuery()

//Equipment
Equipment.newQuery()

//Bank
Bank.newQuery()

//Trade (outgoing)
Trade.Outgoing.newQuery()

//Trade (incoming)
Trade.Incoming.newQuery()

//Looting bag
LootingBag.newQuery()

//Seed vault
SeedVault.newQuery()
```

Utility methods like these exist for the more common inventory types. Queries can be constructed for uncommon inventories by passing an inventory to the SpriteItemQueryBuilder:

```java
new SpriteItemQueryBuilder(Inventories.Documented.INVENTORY)
```

{% endtab %}

{% tab title="Interfaces" %}
The **InterfaceComponentQueryBuilder** can be used to search for **InterfaceComponents**, and can be created using the following:

```java
Interfaces.newQuery()
```

Like the GameObjectQueryBuilder, this can be quite an expensive call, but query speed can be improved signficantly by filtering on **type** and **container:**

```java
Interfaces.newQuery().containers(261).types(InterfaceComponent.Type.SPRITE)
```

{% endtab %}

{% tab title="GameObjects" %}
A **GameObjectQueryBuilder** is used to search for GameObjects (trees, doors etc.), and can be created using the following:

```java
GameObjects.newQuery()
```

GameObject queries are rather expensive, and can take a significant time to run if not optimized correctly. Query speed can be reduced by about 90% by filtering on **type** and **location**:

```java
//By single coordinate
Coordinate coordinate = ...;
GameObjects.newQuery().types(GameObject.Type.PRIMARY).on(coordinate)

//By area
Area area = ...;
GameObjects.newQuery().types(GameObject.Type.PRIMARY).within(area)

```

{% endtab %}

{% tab title="Projectiles" %}
The **ProjectileQueryBuilder** can be used to find projectiles, and the builder can be created using the following:

```java
Projectiles.newQuery()
```

{% endtab %}

{% tab title="Ground Items" %}
The **GroundItemQueryBuilder** can be used to find ground items, and the builder can be created using the following:

```java
GroundItems.newQuery()
```

{% endtab %}

{% tab title="Worlds" %}
The **WorldQueryBuilder** can be used to identify **WorldOverviews** from the world list, which can be used to identify appropriate worlds to hop to. The builder can be created as follows:

```java
Worlds.newQuery()
```

{% endtab %}
{% endtabs %}

### Query Results

**QueryResults** are evaluated lazily when **QueryBuilder#results()** is invoked, so builders can be re-used. QueryResults are a mutable **Collection**, so can be iterated and mutated. Some convenience methods are available to make accessing your desired result easier:

```java
//Getting the first "Cake" in your inventory
SpriteItem cake = Inventory.newQuery().names("Cake").results().first();

//Get the last "Cake" in your inventory
SpriteItem cake = Inventory.newQuery().names("Cake").results().last();

//Get a random "Cake" in your inventory
SpriteItem cake = Inventory.newQuery().names("Cake").results().random();

//Finding the nearest tree to your player
GameObject tree = GameObjects.newQuery().names("Tree").results().nearest();

//Finding the nearest logs on the floor next to the tree
GroundItem logs = GroundItems.newQuery().names("Logs").results().nearestTo(tree);
```

{% hint style="warning" %}
Remember your null checks! RuneScape is a dynamic game and queries are not guaranteed to succeed, so failing to properly null check may result in crashes due to NullPointerExceptions.
{% endhint %}