# Topology - script API

\\

## Topology - script API

### Function: `Topology.query(query: String)`

Query the topology at any point in time. Builder methods available for extracting components, relations and comparing topological queries.

#### Args

* `query` - a [STQL query](/5.1/develop/reference/stql_reference.md).

**Returns:**

`AsyncScriptResult[TopologyScriptApiQueryResponse]`

#### Builder methods

* `at(time: Instant or Timeslice)` - specifes a [time](/5.1/develop/reference/scripting/script-apis/time.md) for which the query should be executed.
  * Use an `instant` to query for transactions that started at a specific timestamp including at any point in the past.
  * Use the `currentTimeslice` to query for all transactions currently started or in progress.
* `repeatAt(time: Instant)` - repeats the same query but at a different exact [time](/5.1/develop/reference/scripting/script-apis/time.md).
* `diff(queryResult: TopologyScriptApiQueryResponse)` - compares this query with another query. A query should be the result of a call to this function.
* `diffWithPrev(queryResult: TopologyScriptApiQueryResponse)` - compares this query with the last query in the chain. A query should be the result of a call to this function. This builder method is only available after the `diff` builder method was called.
* `components()` - returns a summary of the components. After this builder method no more builder methods can be called.
* `fullComponents()` - returns the component with all their data. After this builder method no more builder methods can be called.
* `problems()` - returns problems for a given query along with the root cause and its contributing problems.
* `relations()` - returns a summary of the relations. After this builder method no more builder methods can be called.
* `fullRelations()` - returns the relations with all their data. After this builder method no more builder methods can be called.

#### Examples

* Get the test environment:

  ```
  Topology.query('environment in ("test")')
  ```
* Get the test environment yesterday:

  ```
  Topology.query('environment in ("test")').at('-1d')
  ```
* Get test environment one hour ago, two hours ago and three hours ago.

  ```
  Topology.query('environment in ("test")').at('-1h').repeatAt('-2h').repeatAt('-3h')
  ```
* Get the component that differ between the test and production environment:

  ```
  Topology.query('environment in ("test")').diff(Topology.query('environment in ("production")')).components()
  ```
* Get the difference between the test environment one week ago and now:

  ```
  def q = 'environment in ("test")'
  Topology.query(q).at('-1w').diff(Topology.query(q))
  ```
* Get all the names of components from the test environment using [`thenCollect`](/5.1/develop/reference/scripting/async-script-result.md#transforming-a-list-using-thencollect):

  ```
  Topology.query('environment in ("test")')
    .components()
    .thenCollect { it.name }
  ```
* Get the first root problem's first failing check - likely a major root cause of a problem in the queried topology:

  ```
    Topology
    .query('environment in ("test")')
    .problems()
    .then{ problems -> 
        problems.isEmpty()? null : problems[0].failingCheckNames[0] 
    }
  ```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://archivedocs.stackstate.com/5.1/develop/reference/scripting/script-apis/topology.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.