> For the complete documentation index, see [llms.txt](https://boxlang.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boxlang.ortusbooks.com/boxlang-language/reference/types/set.md).
# set
The primary Set class in BoxLang.
This class wraps a `java.util.Set` and provides full BoxLang integration: member-function dispatch via `FunctionService`, change listeners, metadata, and JSON serialization.
BoxSet supports three backing variants chosen at construction:
* `Type#DEFAULT` — `HashSet`, fastest, no order guarantee
* `Type#LINKED` — `LinkedHashSet`, preserves insertion order
* `Type#SORTED` — `TreeSet`, natural ordering (uses `Compare`)
This class is named `BoxSet` (rather than `Set`) to avoid collision with `java.util.Set` throughout the BoxLang codebase.
## Set Methods
add(value=[any])
Add an element to a Set, deduplicating automatically.
If the value is already present, the call is a no-op. The Set is modified in place and returned to support method chaining.
### Method Signature
```
add(value=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | ----- | -------- | -------------------------------------------------- | ------- |
| `value` | `any` | `true` | The value to add. Duplicates are silently ignored. | |
addAll(values=[any])
Add every element of a collection into a Set, deduplicating automatically.
The source collection can be an Array, another Set, a list-delimited String, or any value castable to a Set. The Set is modified in place and returned to support method chaining.
### Method Signature
```
addAll(values=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | ----- | -------- | ---------------------------------------------------------------------------------------------------------- | ------- |
| `values` | `any` | `true` | The collection of values to add. Accepts an Array, Set, list-delimited String, or any castable collection. | |
any(callback=[function:Predicate])
Test whether at least one element of a Set satisfies a predicate.
Iteration short-circuits on the first element for which the predicate returns true. Returns false for an empty Set. The predicate receives the element value, its 1-based ordinal position, and the Set itself.
### Method Signature
```
any(callback=[function:Predicate])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `callback` | `function:Predicate` | `true` | Predicate invoked for each element. Receives (value, ordinal, set).
Short-circuits on the first true result.
| |
append(value=[any])
Add an element to a Set, deduplicating automatically.
If the value is already present, the call is a no-op. The Set is modified in place and returned to support method chaining.
### Method Signature
```
append(value=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | ----- | -------- | -------------------------------------------------- | ------- |
| `value` | `any` | `true` | The value to add. Duplicates are silently ignored. | |
clear()
Remove all elements from a Set, leaving it empty.
The Set is modified in place and returned to support method chaining.
### Method Signature
```
clear()
```
### Arguments
This function does not accept any arguments
contains(value=[any])
Test whether a Set contains a given value using BoxLang value equality.
Returns true if the value is present, false otherwise.
### Method Signature
```
contains(value=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | ----- | -------- | ---------------------- | ------- |
| `value` | `any` | `true` | The value to look for. | |
containsAll(values=[any])
Test whether a Set contains every element of a given collection.
The collection can be an Array, another Set, a list-delimited String, or any value castable to a Set. Returns true only if all elements are present.
### Method Signature
```
containsAll(values=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | ----- | -------- | ---------------------------------------------------------------------------------------------------------------- | ------- |
| `values` | `any` | `true` | The collection of values to check for. Accepts an Array, Set, list-delimited String, or any castable collection. | |
delete(value=[any])
Remove an element from a Set.
If the value is not present the call is a no-op. The Set is modified in place and returned to support method chaining.
### Method Signature
```
delete(value=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | ----- | -------- | ---------------------------------------------------------------------- | ------- |
| `value` | `any` | `true` | The value to remove. If the value is not present, the call is a no-op. | |
difference(otherSet=[any])
Compute the relative complement (A − B) of two Sets.
Returns a new Set containing all elements that are in A but not in B. The result is a new Set of the same variant as A; neither input is modified.
### Method Signature
```
difference(otherSet=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | ----- | -------- | ------------------------------------------------------------- | ------- |
| `otherSet` | `any` | `true` | The set to subtract (B). Accepts any value castable to a Set. | |
duplicate(deep=[boolean])
Duplicates an object - either shallow or deep
### Method Signature
```
duplicate(deep=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | --------- | -------- | ------------------------------------------------------------------------------------------------- | ------- |
| `deep` | `boolean` | `false` | Whether to deep copy the object or make a shallow copy (e.g. only the top level keys in a struct) | `true` |
each(callback=[function:Consumer])
Invoke a callback for every element of a Set.
The callback receives the element value, its 1-based ordinal position, and the Set itself; single-argument callbacks receive only the value. Iteration follows the natural order of the underlying variant. Use setMap() if you need a transformed result.
### Method Signature
```
each(callback=[function:Consumer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:Consumer` | `true` | Invoked for each element. Receives (value, ordinal, set); single-argument callbacks
receive only the value.
| |
equals(otherSet=[any])
Test whether two Sets contain exactly the same elements.
The comparison is variant-agnostic: a hash Set and a linked Set with identical elements are considered equal. Returns true if both sets have the same size and every element of one is present in the other.
### Method Signature
```
equals(otherSet=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | ----- | -------- | --------------------------------------------------------------- | ------- |
| `otherSet` | `any` | `true` | The second set to compare. Accepts any value castable to a Set. | |
every(callback=[function:Predicate])
Test whether every element of a Set satisfies a predicate.
Iteration short-circuits on the first element for which the predicate returns false. Returns true for an empty Set (vacuous truth). The predicate receives the element value, its 1-based ordinal position, and the Set itself.
### Method Signature
```
every(callback=[function:Predicate])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:Predicate` | `true` | Predicate invoked for each element. Receives (value, ordinal, set).
Short-circuits on the first false result.
| |
filter(callback=[function:Predicate])
Return a new Set containing only the elements of the source Set for which the predicate returns true.
The result is a new Set of the same variant as the source; the source is not modified. The predicate receives the element value, its 1-based ordinal position, and the Set itself.
### Method Signature
```
filter(callback=[function:Predicate])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `callback` | `function:Predicate` | `true` | Predicate invoked for each element. Receives (value, ordinal, set).
Elements for which this returns true are included in the result.
| |
find(callback=[function:Predicate])
Return the first element of a Set for which the predicate returns true, or null if no element matches.
Iteration follows the natural order of the underlying variant and stops at the first match. The predicate receives the element value, its 1-based ordinal position, and the Set itself.
### Method Signature
```
find(callback=[function:Predicate])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:Predicate` | `true` | Predicate invoked for each element. Receives (value, ordinal, set).
Iteration stops at the first element for which this returns true.
| |
has(value=[any])
Test whether a Set contains a given value using BoxLang value equality.
Returns true if the value is present, false otherwise.
### Method Signature
```
has(value=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | ----- | -------- | ---------------------- | ------- |
| `value` | `any` | `true` | The value to look for. | |
hash(algorithm=[string], encoding=[string], numIterations=[integer])
Creates an algorithmic hash of an object
### Method Signature
```
hash(algorithm=[string], encoding=[string], numIterations=[integer])
```
### Arguments
| Argument | Type | Required | Description | Default |
| --------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------- | ------- |
| `algorithm` | `string` | `false` | The supported `java.security.MessageDigest` algorithm (case-insensitive) or "quick" for an insecure 64-bit hash | `MD5` |
| `encoding` | `string` | `false` | Applicable to strings ( default "utf-8" ) | `utf-8` |
| `numIterations` | `integer` | `false` | The number of iterations to re-digest the object ( default 1 ); | `1` |
intersection(otherSet=[any])
Compute the intersection (A ∩ B) of two Sets, returning a new Set that contains only the elements present in both A and B.
The result is a new Set of the same variant as A; neither input is modified.
### Method Signature
```
intersection(otherSet=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | ----- | -------- | -------------------------------------------------------- | ------- |
| `otherSet` | `any` | `true` | The second set (B). Accepts any value castable to a Set. | |
isDisjointFrom(otherSet=[any])
Test whether two Sets share no common elements, i.e.
their intersection is empty. Returns true if the two Sets are disjoint, false if they have at least one element in common.
### Method Signature
```
isDisjointFrom(otherSet=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | ----- | -------- | ----------------------------------------------------------------------- | ------- |
| `otherSet` | `any` | `true` | The second set to compare against. Accepts any value castable to a Set. | |
isEmpty()
Test whether a Set contains no elements.
Returns true for an empty Set, false if it has one or more elements.
### Method Signature
```
isEmpty()
```
### Arguments
This function does not accept any arguments
isSubsetOf(otherSet=[any])
Test whether every element of set A is also contained in set B, i.e.
A ⊆ B. An empty set is always a subset of any set. Returns true if A is a subset of B, false otherwise.
### Method Signature
```
isSubsetOf(otherSet=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | ----- | -------- | ---------------------------------------------------------------- | ------- |
| `otherSet` | `any` | `true` | The candidate superset (B). Accepts any value castable to a Set. | |
isSupersetOf(otherSet=[any])
Test whether every element of set B is also contained in set A, i.e.
A ⊇ B. A set is always a superset of the empty set. Returns true if A is a superset of B, false otherwise.
### Method Signature
```
isSupersetOf(otherSet=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | ----- | -------- | -------------------------------------------------------------- | ------- |
| `otherSet` | `any` | `true` | The candidate subset (B). Accepts any value castable to a Set. | |
len()
Returns the absolute value of a number
### Method Signature
```
len()
```
### Arguments
This function does not accept any arguments
length()
Returns the absolute value of a number
### Method Signature
```
length()
```
### Arguments
This function does not accept any arguments
map(callback=[function:Function])
Apply a transform function to every element of a Set and collect the deduplicated results into a new Set of the same variant.
The source Set is not modified. The callback receives the element value, its 1-based ordinal position, and the original Set.
### Method Signature
```
map(callback=[function:Function])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | ------------------- | -------- | ------------------------------------------------------------------- | ------- |
| `callback` | `function:Function` | `true` | Receives `(value, ordinal, set)` and returns the transformed value. | |
none(callback=[function:Predicate])
Test whether no element of a Set satisfies a predicate.
Iteration short-circuits on the first element for which the predicate returns true. Returns true for an empty Set. The predicate receives the element value, its 1-based ordinal position, and the Set itself.
### Method Signature
```
none(callback=[function:Predicate])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `callback` | `function:Predicate` | `true` | Predicate invoked for each element. Receives (value, ordinal, set).
Short-circuits on the first true result.
| |
parallelStream()
No description available
### Method Signature
```
parallelStream()
```
### Arguments
This function does not accept any arguments
reduce(callback=[function:BiFunction], initialValue=[any])
Left-fold a Set with an accumulator function, reducing it to a single value.
The callback receives the current accumulator, the element value, its 1-based ordinal position, and the Set itself, and returns the new accumulator. Iteration follows the natural order of the underlying variant.
### Method Signature
```
reduce(callback=[function:BiFunction], initialValue=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:BiFunction` | `true` | Receives `(accumulator, value, ordinal, set)` and returns the new accumulator. | |
| `initialValue` | `any` | `false` | The starting accumulator value. If omitted, the first element is used as the initial value. | |
reject(callback=[function:Predicate])
Return a new Set containing only the elements of the source Set for which the predicate returns false (the inverse of setFilter).
The result is a new Set of the same variant as the source; the source is not modified. The predicate receives the element value, its 1-based ordinal position, and the Set itself.
### Method Signature
```
reject(callback=[function:Predicate])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `callback` | `function:Predicate` | `true` | Predicate invoked for each element. Receives (value, ordinal, set).
Elements for which this returns false are included in the result.
| |
remove(value=[any])
Remove an element from a Set.
If the value is not present the call is a no-op. The Set is modified in place and returned to support method chaining.
### Method Signature
```
remove(value=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | ----- | -------- | ---------------------------------------------------------------------- | ------- |
| `value` | `any` | `true` | The value to remove. If the value is not present, the call is a no-op. | |
removeAll(values=[any])
Remove every element of a collection from a Set, leaving only the elements that are not in the collection.
The Set is modified in place and returned to support method chaining. Elements not present in the Set are silently skipped.
### Method Signature
```
removeAll(values=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | ----- | -------- | ------------------------------------------------------------------------------------------------------------- | ------- |
| `values` | `any` | `true` | The collection of values to remove. Accepts an Array, Set, list-delimited String, or any castable collection. | |
retainAll(values=[any])
Retain only the elements of a Set that are also present in the given collection, removing everything else.
This is the in-place equivalent of computing an intersection. The Set is modified in place and returned to support method chaining.
### Method Signature
```
retainAll(values=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| -------- | ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `values` | `any` | `true` | The collection whose membership determines which elements are kept. Accepts an Array, Set,
list-delimited String, or any castable collection.
| |
size()
Returns the absolute value of a number
### Method Signature
```
size()
```
### Arguments
This function does not accept any arguments
some(callback=[function:Predicate])
Test whether at least one element of a Set satisfies a predicate.
Iteration short-circuits on the first element for which the predicate returns true. Returns false for an empty Set. The predicate receives the element value, its 1-based ordinal position, and the Set itself.
### Method Signature
```
some(callback=[function:Predicate])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `callback` | `function:Predicate` | `true` | Predicate invoked for each element. Receives (value, ordinal, set).
Short-circuits on the first true result.
| |
stream()
No description available
### Method Signature
```
stream()
```
### Arguments
This function does not accept any arguments
symmetricDifference(otherSet=[any])
Compute the symmetric difference (A △ B) of two Sets, returning the elements that are in exactly one of the two Sets but not in both.
Equivalent to `(A ∪ B) − (A ∩ B)`. The result is a new Set of the same variant as A; neither input is modified.
### Method Signature
```
symmetricDifference(otherSet=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | ----- | -------- | -------------------------------------------------------- | ------- |
| `otherSet` | `any` | `true` | The second set (B). Accepts any value castable to a Set. | |
toArray()
Convert a Set to an Array, preserving the iteration order of the underlying variant.
For a LINKED Set the insertion order is preserved; for a SORTED Set the natural ordering applies; for a default hash Set the order is undefined. The source Set is not modified.
### Method Signature
```
toArray()
```
### Arguments
This function does not accept any arguments
toJSON(queryFormat=[string], useSecureJSONPrefix=[string], useCustomSerializer=[boolean], pretty=[boolean])
Converts a BoxLang variable into a JSON (JavaScript Object Notation) string according to the specified options.
## Query Format Options
The `queryFormat` argument determines how queries are serialized:
* `row` or `false`: Serializes the query as a top-level struct with two keys: `columns` (an array of column names) and `data` (an array of arrays representing each row's data).
* `column` or `true`: Serializes the query as a top-level struct with three keys: `rowCount` (the number of rows), `columns` (an array of column names), and `data` (a struct where each key is a column name and the value is an array of values for that column).
* `struct`: Serializes the query as an array of structs, where each struct represents a row of data.
## Usage
```
// Convert a query to JSON
myQuery = ...;
json = jsonSerialize( myQuery, queryFormat="row" );
// Convert a list to JSON
myList = "foo,bar,baz";
jsonList = jsonSerialize( myList );
```
### Method Signature
```
toJSON(queryFormat=[string], useSecureJSONPrefix=[string], useCustomSerializer=[boolean], pretty=[boolean])
```
### Arguments
| Argument | Type | Required | Description | Default |
| --------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `queryFormat` | `string` | `false` | If the variable is a query, specifies whether to serialize the query by rows or by columns. Valid values are:
row same as false, column same as true, or struct. Defaults to row.
| |
| `useSecureJSONPrefix` | `string` | `false` | If true, the JSON string is prefixed with a secure JSON prefix. (Not implemented yet) | `false` |
| `useCustomSerializer` | `boolean` | `false` | If true, the JSON string is serialized using a custom serializer. (Not implemented yet) | |
| `pretty` | `boolean` | `false` | If true, the JSON string is formatted with indentation and line breaks for readability. Defaults to false. | `false` |
toList(delimiter=[string])
Join the elements of a Set into a delimited string.
Each element is cast to a String before joining. For LINKED Sets the insertion order is preserved; for SORTED Sets the natural ordering applies; for default hash Sets the order is undefined.
### Method Signature
```
toList(delimiter=[string])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ----------- | -------- | -------- | ----------------------------------------------------------- | ------- |
| `delimiter` | `string` | `false` | The delimiter to place between elements. Defaults to `","`. | `,` |
toModifiable()
Convert an array, struct, query or set to its Modifiable counterpart.
### Method Signature
```
toModifiable()
```
### Arguments
This function does not accept any arguments
toUnmodifiable()
Convert an array, struct, query or set to its Unmodifiable counterpart.
### Method Signature
```
toUnmodifiable()
```
### Arguments
This function does not accept any arguments
union(otherSet=[any])
Compute the union (A ∪ B) of two Sets, returning a new Set that contains all elements from both.
Duplicates are automatically deduplicated. The result is a new Set of the same variant as A; neither input is modified.
### Method Signature
```
union(otherSet=[any])
```
### Arguments
| Argument | Type | Required | Description | Default |
| ---------- | ----- | -------- | -------------------------------------------------------- | ------- |
| `otherSet` | `any` | `true` | The second set (B). Accepts any value castable to a Set. | |
### Creating sets using the function `setNew`
```java
// Create a default set (hash-based, no ordering)
mySet = setNew();
// Create a linked set which will maintain insertion order
mySet = setNew( type="linked" );
// Create a sorted set which will keep elements in natural order
mySet = setNew( type="sorted" );
// Create a set seeded with values (duplicates removed)
mySet = setNew( values=[ 1, 2, 2, 3 ] );
// Create a case-sensitive set
mySet = setNew( values=[ "Hello", "hello", "HELLO" ], caseSensitive=true );
```
### Creating sets using literal syntax
```java
// Create a set with values
mySet = set{ 1, 2, 3 };
// Create an empty set
emptySet = set{};
// Spread an array into a set
arr = [ 3, 4, 5 ];
s = set{ 1, 2, ...arr };
// Spread another set
other = set{ 2, 3 };
s = set{ 1, ...other, 4 };
// Spread a range
s = set{ ...(1..5) };
```
### Creating sets from varargs
```java
// setOf deduplicates automatically
s = setOf( 1, 2, 2, 3 );
// Result: Set with 3 elements
```
### Converting arrays to sets
```java
// Convert array to default set
s = [ 1, 2, 2, 3 ].toSet();
// Convert to linked (insertion-ordered) set
s = [ "c", "a", "b", "a" ].toSet( "linked" );
// Convert to sorted set
s = [ 9, 1, 5, 3 ].toSet( "sorted" );
```
### Converting strings to sets
```java
// Split comma-delimited string to set
s = "a,b,c,a".listToSet();
// Custom delimiter with type
s = "a|b|c|b".listToSet( delimiter="|", type="linked" );
```
### Set membership and mutation
```java
s = setNew();
// Add elements (add and append are aliases)
s.add( "apple" );
s.append( "banana" );
// Test membership (contains and has are aliases)
s.contains( "apple" ); // true
s.has( "banana" ); // true
// Remove elements (remove and delete are aliases)
s.remove( "apple" );
s.delete( "banana" );
// Size (size, len, length are aliases)
s.size();
s.len();
s.length();
```
### Set algebra
```java
a = set{ 1, 2, 3 };
b = set{ 3, 4, 5 };
// Union - all unique elements
u = a.union( b ); // {1, 2, 3, 4, 5}
u = a + b; // operator shorthand
// Intersection - common elements
i = a.intersection( b ); // {3}
i = a * b; // operator shorthand
// Difference - in A but not B
d = a.difference( b ); // {1, 2}
d = a - b; // operator shorthand
// Symmetric difference - in either but not both
x = a.symmetricDifference( b ); // {1, 2, 4, 5}
x = a ^ b; // operator shorthand
```
### Functional operations
```java
s = [ 1, 2, 3, 4, 5 ].toSet();
// Map - transform elements
doubled = s.map( v -> v * 2 );
// Filter - keep matching
evens = s.filter( v -> v % 2 == 0 );
// Reduce - combine to single value
total = s.reduce( (acc, v) -> acc + v, 0 );
// Predicates
s.every( v -> v > 0 ); // true
s.some( v -> v > 4 ); // true
s.none( v -> v < 0 ); // true
// Find first match
found = s.find( v -> v > 2 );
```
### Converting sets back
```java
s = setNew( type="linked", values=[ "a", "b", "c" ] );
// To array
arr = s.toArray();
// To list string
list = s.toList();
list = s.toList( "-" ); // custom delimiter
```
### Struct key/value sets
```java
data = { name: "Luis", age: 42, email: "x@y.z" };
// Get keys as a set
keys = data.keySet();
// Get values as a set (deduplicated)
values = data.valueSet();
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://boxlang.ortusbooks.com/boxlang-language/reference/types/set.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.