Arrays allow you to store and manipulate collections of data. They can be declared in both single-line and multi-line formats.
Syntax
A collection of elements of the same type
Type[] // Basic array
(int | string)[] // Array of unions
int[][] // Multi-dimensional array
Declaration Syntax
Arrays can be declared inline or across multiple lines:
{
key1 [value1, value2, value3],
key2 [
value1,
value2,
value3
],
key3 [
{
subkey1 "valueA",
subkey2 "valueB"
},
{
subkey1 "valueC",
subkey2 "valueD"
}
]
}
Key Points:
- Commas are optional for multi-line arrays but recommended for clarity
- Nested arrays are supported for complex data structures
- Arrays can contain objects with key-value pairs
Basic Array Example
function DescriptionGame(items: string[]) -> string {
client "openai/gpt-4o-mini"
prompt #"
What 3 words best describe all of these: {{ items }}.
"#
}
test FruitList {
functions [DescriptionGame]
args { items ["apple", "banana", "cherry"] }
}
Generated Types
from typing import List
items: List[str] = ["apple", "banana", "cherry"]
Multi-line Arrays
For better readability, arrays can span multiple lines:
test CityDescription {
functions [DescriptionGame]
args { items [
"New York",
"Los Angeles",
"Chicago"
]
}
}
Arrays of Complex Types
Arrays of Classes
class Person {
name string
age int
}
function AnalyzePeople(people: Person[]) -> string {
client "openai/gpt-4o-mini"
prompt #"
Analyze these people: {{ people }}
"#
}
test PeopleAnalysis {
functions [AnalyzePeople]
args {
people [
{ name "Alice", age 30 },
{ name "Bob", age 25 }
]
}
}
Generated Types
from typing import List
from baml_client.types import Person
people: List[Person] = [
Person(name="Alice", age=30),
Person(name="Bob", age=25)
]
Union Arrays
Arrays can contain union types:
function ProcessMixed(data: (int | string)[]) -> string {
client "openai/gpt-4o-mini"
prompt #"
Process this mixed data: {{ data }}
"#
}
test MixedData {
functions [ProcessMixed]
args { data [1, "hello", 42, "world"] }
}
Generated Types
from typing import List, Union
data: List[Union[int, str]] = [1, "hello", 42, "world"]
Multi-dimensional Arrays
Nested arrays for matrix-like data:
function AnalyzeMatrix(matrix: int[][]) -> string {
client "openai/gpt-4o-mini"
prompt #"
Analyze this matrix: {{ matrix }}
"#
}
test MatrixAnalysis {
functions [AnalyzeMatrix]
args {
matrix [
[1, 2, 3],
[4, 5, 6],
[7, 8, 9]
]
}
}
Generated Types
from typing import List
matrix: List[List[int]] = [
[1, 2, 3],
[4, 5, 6],
[7, 8, 9]
]
Optional Arrays
Arrays can be optional:
function ProcessOptionalList(items: string[]?) -> string {
client "openai/gpt-4o-mini"
prompt #"
{% if items %}
Process these items: {{ items }}
{% else %}
No items provided.
{% endif %}
"#
}
Generated Types
from typing import List, Optional
items: Optional[List[str]] = None
# or
items: Optional[List[str]] = ["item1", "item2"]
Arrays of Enums
enum Color {
Red
Green
Blue
}
function AnalyzeColors(colors: Color[]) -> string {
client "openai/gpt-4o-mini"
prompt #"
Analyze these colors: {{ colors }}
"#
}
test ColorAnalysis {
functions [AnalyzeColors]
args { colors [Red, Green, Blue] }
}
Generated Types
from typing import List
from enum import StrEnum
class Color(StrEnum):
Red = "Red"
Green = "Green"
Blue = "Blue"
colors: List[Color] = [Color.Red, Color.Green, Color.Blue]
Constraints and Validation
Important Constraints:
- Array types cannot be optional themselves (use
Type[]? instead of Type?[])
- Arrays can be nested to create multi-dimensional structures
- All elements must be of the same type (or match the union type)
Best Practices
- Use multi-line format for arrays with more than 3 elements for better readability
- Include trailing commas in multi-line arrays for easier editing
- Use descriptive variable names that indicate the array contains multiple items
- Consider using classes for arrays of complex structured data