fetch_fields

The mysqli_fetch_fields() function returns an array of objects that describe the columns (fields) of a MySQLi result set — their names, types, lengths, source tables, and flags. It reads metadata about the columns, not the row data itself. This page explains the syntax, what each field object contains, when you would reach for it, and the common gotchas.

Syntax

mysqli_fetch_fields(mysqli_result $result): array

In the object-oriented style the same call is $result->fetch_fields().

• $result — a result set returned by mysqli_query(), mysqli_store_result(), or mysqli_use_result().
• Return value — an array of stdClass objects, one per column, in the order the columns appear in the result. Each object exposes properties such as name, orgname, table, orgtable, type, length, max_length, decimals, and flags.

What each field object contains

When would I use it?

Reach for mysqli_fetch_fields() when you need to work with a query result generically — without knowing the columns ahead of time. Typical cases:

• Building an admin/data-grid that renders any SELECT * query, using column names for table headers.
• Exporting results to CSV with a header row.
• Inspecting whether a column is a primary key or auto-increment before generating an edit form.

If you only need the column names, this is the most direct way to get them. To pull one field's description at a time, use mysqli_fetch_field() instead, and to count the columns use mysqli_field_count().

Example: list every column in a result set

<?php
$mysqli = mysqli_connect("localhost", "user", "password", "shop");

$result = mysqli_query($mysqli, "SELECT id, name, price FROM products");

$fields = mysqli_fetch_fields($result);

foreach ($fields as $field) {
    printf("Name: %s, Type: %d, Length: %d\n",
        $field->name, $field->type, $field->length);
}

mysqli_free_result($result);
mysqli_close($mysqli);
?>

The foreach loop walks the array of field objects and prints the name, type code, and defined length of each column. For the three selected columns the output looks like:

Name: id, Type: 3, Length: 11
Name: name, Type: 253, Length: 255
Name: price, Type: 246, Length: 10

The numeric type values come from the MYSQLI_TYPE_* constants — for example 3 is MYSQLI_TYPE_LONG (an INT) and 253 is MYSQLI_TYPE_VAR_STRING (a VARCHAR).

Building a CSV header from the field names

Because the field array is generic, you can build a header row for any query without hard-coding column names:

<?php
$result = mysqli_query($mysqli, "SELECT * FROM products");

$header = array_map(
    fn($field) => $field->name,
    mysqli_fetch_fields($result)
);

echo implode(",", $header), "\n"; // id,name,price

array_map() turns the array of field objects into a plain array of names, and implode() joins them with commas.

Gotchas

• mysqli_fetch_fields() is metadata only. It does not move the row cursor and does not return any row data — combine it with mysqli_fetch_assoc() or mysqli_fetch_array() to read the actual rows.
• max_length is 0 with unbuffered results. It is only populated when the full result set is buffered on the client via mysqli_store_result() (which mysqli_query() uses by default). With mysqli_use_result() the value stays 0.
• type and flags are integers, not strings. Compare them against the MYSQLI_TYPE_* and MYSQLI_*_FLAG constants rather than magic numbers, so the intent is clear.
• Always check that $result is truthy before calling the function — a failed query returns false, and passing false raises an error.

Related functions

• mysqli_fetch_field() — fetch one column's metadata at a time.
• mysqli_field_count() — count the columns in the result.
• mysqli_field_seek() — move the field cursor to a specific column.
• mysqli_fetch_assoc() — read result rows as associative arrays.

Practice