> ## Documentation Index
> Fetch the complete documentation index at: https://docs.speckle.systems/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs contain multiple Speckle product experiences. For Speckle 2026.9, prefer /next/ pages for the topics and changes they cover. The navigation label Current does not override this version-specific precedence.
> Coverage under /next/ is incremental. Use Current documentation for unchanged topics and when a /next/ page says coverage is unavailable or explicitly refers you to Current. Do not infer a feature was removed from a missing page.
> Read the page-specific documentation status, applicability, affected guidance and replacement links in agent-only content. Impacted, changed and superseded apply only to the stated scope; they do not mean the entire feature is deprecated. Historical connector guides apply only to the legacy connector described.
> Match guidance to the customer's deployment version, model data format and connector. Respect plan, permission and compatibility restrictions. If an unknown version or data format changes the answer, ask a focused clarification; do not infer deployment version from the date alone.

# Queries

> Queries are a simple mechanism that allows the user to perform several operations in a contained way.

The supported operations are

* Project a point
* Unproject a point
* Intersection test
* Occlusion test

Queries are not meant to be used directly, but rather through the viewer's [*query*](/developers/viewer/viewer-api#query) function

## Typedefs

### IntersectionQuery

```typescript theme={null}
interface IntersectionQuery extends Query {
  point: { x: number; y: number; z?: number; w?: number }
  tolerance?: number
  operation: 'Occlusion' | 'Pick'
}
```

* **point**: The point to test for intersections
* *optional* **tolerance**: Tolerance for intersection
* **operation**: The query operation type

Based on the operation modes:

* `Occlusion`: Test if a point in the scene is being occluded by the scene's geometry
* `Pick`: Cast a camer ray to the specified point and return all intersection results

<Warning>
  Pick filter from
  [*ObjectPickConfiguration*](/developers/viewer/speckle-renderer-api#objectpickconfiguration) **do
  not** apply here!
</Warning>

### IntersectionQueryResult

```typescript theme={null}
interface IntersectionQueryResult {
  objects: Array<{
    guid: string
    object?: Record<string, unknown>
    point: { x: number; y: number; z: number }
  }> | null
}
```

* **guid**: The id of the object
* *optional* **object**: The raw data of the intersected object
* **point**: The point of intersection

### PointQuery

```typescript theme={null}
interface PointQuery extends Query {
  point: { x: number; y: number; z?: number; w?: number }
  operation: 'Project' | 'Unproject'
}
```

* **point**: The point to run the operation on
* **operation**: The operation type

Based on the operation modes:

* `Project`: Projects a world point onto the screen. Result is in NDC
* `Unproject`: Unprojects an NDC point into a world point

### PointQueryResult

```typescript theme={null}
interface PointQueryResult {
  x: number
  y: number
  z?: number
  w?: number
}
```

The result is a point of variable component length

### Query

```typescript theme={null}
interface Query {
  id?: string
  operation: string
}
```

* *optional* **id**: Currently unused
* **operation**: The operation type

### QueryArgsResultMap

```typescript theme={null}
type QueryArgsResultMap = {
  Project: PointQueryResult
  Unproject: PointQueryResult
  Occlusion: IntersectionQueryResult
  Pick: IntersectionQueryResult
} & { [key: string]: unknown }
```

Mapping between the query type and query result type.

### QueryOperation

```typescript theme={null}
type QueryOperation = 'Project' | 'Unproject' | 'Occlusion' | 'Pick'
```

Query operation type values

### QueryResult

```typescript theme={null}
type QueryResult = PointQueryResult | IntersectionQueryResult
```

Query result type values


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.