A multi-dimensional array is an array whose elements are themselves arrays — useful for grid-shaped or table-like data, like a spreadsheet, a game board, or rows and columns pulled from a database.
ColdFusion directly supports up to three dimensions. A 2D array is really just a 1D array where each element happens to be another array — so a "row" can have a different length than the row next to it, unlike a fixed-size grid in some other languages.
Learning Objectives
After completing this lesson, you'll be able to:
- Create a 2D array with arrayNew(2) or nested literal syntax.
- Access and modify elements in a 2D array using row and column indices.
- Create a 3D array.
- Populate a 2D array from query results.
- Loop through a 2D array with nested loops.
Creating a 2D Array
The first index selects the row (the inner array); the second index selects the position within that row.
Creating a 3D Array
3D arrays are uncommon in everyday web development — most real-world grid data only needs two dimensions.
Looping Through a 2D Array
Each row can have a different length, so the inner loop measures arrayLen(grid[row]) for that specific row, not a fixed column count.
Populating a 2D Array From Query Results
Query data can't be dropped into an array all at once — it has to be looped, one row at a time. This is a common real-world pattern for turning database results into a plain array structure.
<cfquery name="employees" datasource="cfdocexamples">
SELECT Emp_ID, LastName, FirstName, Email
FROM Employees
</cfquery>
<cfset myArray = arrayNew(2)>
<cfloop query="employees">
<cfset myArray[currentRow][1] = Emp_ID>
<cfset myArray[currentRow][2] = LastName>
<cfset myArray[currentRow][3] = FirstName>
<cfset myArray[currentRow][4] = Email>
</cfloop>currentRow is available automatically inside a <cfloop query="...">, and starts at 1 — matching the array's 1-based indexing.
Real-World Example: Tic-Tac-Toe Board
Common Beginner Mistakes
Mixing up row and column order
grid[row][col] and grid[col][row] are not the same thing unless the grid happens to be symmetric. Be consistent about which index means what.
Assuming every row has the same length
Because ColdFusion 2D arrays are really arrays of independent 1D arrays, nothing enforces equal row lengths. Looping with a fixed column count instead of measuring arrayLen(grid[row]) can throw an out-of-bounds error on a shorter row.
Trying to load an entire query into an array in one step
There's no single function that converts a whole query result into a 2D array at once — you loop through the query and assign each row's values manually, as shown above.
Best Practices
- Reach for a 2D array for genuinely grid-shaped data — for a simple list of records, an array of structs (covered later in this module) usually reads more clearly than numbered columns.
- Measure each row's own length in nested loops rather than assuming a fixed column count.
- Keep 3D+ arrays rare — if the data is naturally that complex, consider whether a different structure (nested structs, or an array of structs) would be easier to read.
Interview Questions
What is a 2D array really, under the hood, in ColdFusion?
A 1D array whose elements are themselves 1D arrays — not a fixed grid, so rows can have different lengths.
How many dimensions does ColdFusion directly support?
Up to three, via arrayNew(1), arrayNew(2), or arrayNew(3).
How do you populate an array from a query's results?
Loop through the query with <cfloop query="...">, and inside the loop assign each column's value into the array at the current row, using the loop's automatic currentRow variable as the index.
Summary
In this lesson, you learned how to create and access 2D and 3D arrays, loop through a 2D array with nested loops, and populate a 2D array from query results — one of the most common real-world uses of multi-dimensional arrays.
What's Next?
The next lesson covers adding and removing array elements — append, prepend, insert, delete, and the stack/queue-style push, pop, shift, and unshift functions.