field_seek

This article covers the mysqli_field_seek() function in PHP, which sets the field cursor to a specified field offset in a MySQLi result set. We will explain what the field cursor is, when you would reach for this function, document its parameters and return value, and walk through working examples.

What is the field cursor?

When you run a SELECT query with mysqli_query(), MySQLi returns a result set that carries metadata about each column (its name, table, type, length, and flags). That metadata is read one column at a time using mysqli_fetch_field(), and an internal pointer — the field cursor — tracks which column you will read next.

mysqli_field_seek() lets you move that pointer to any column offset, so the next call to mysqli_fetch_field() returns metadata for the column you chose instead of the next one in sequence.

Two things are easy to confuse, so keep them separate:

• The field cursor controls which column's metadata you read — moved with mysqli_field_seek().
• The row cursor controls which data row you read — moved with mysqli_data_seek().

This function only touches the field cursor; it never changes which rows of data are returned.

Syntax

mysqli_field_seek(mysqli_result $result, int $index): true

In object-oriented style the equivalent method is $result->field_seek($index).

Parameters

• result — A mysqli_result object returned by mysqli_query(), mysqli_store_result(), or mysqli_use_result().
• index — The zero-based field offset to seek to. It must be between 0 and the number of fields minus one (see mysqli_field_count()). An invalid offset triggers a warning.

Return value

Returns true. (Historically the procedural form documented a boolean; since PHP 8.0 it always returns true and raises a ValueError for an out-of-range offset.)

Basic usage

Call the function on a valid result set, then fetch the field whose metadata you want:

<?php
$mysqli = mysqli_connect("localhost", "username", "password", "database");

if (mysqli_connect_errno()) {
    die("Connection failed: " . mysqli_connect_error());
}

$result = mysqli_query($mysqli, "SELECT id, name, email FROM users");

if (!$result) {
    die("Query failed: " . mysqli_error($mysqli));
}

// Skip ahead to the third column (offset 2 = "email").
mysqli_field_seek($result, 2);
$field = mysqli_fetch_field($result);

printf("Field name: %s\n", $field->name); // Field name: email

mysqli_close($mysqli);
?>

Here the query selects three columns. Offsets are zero-based, so offset 0 is id, 1 is name, and 2 is email. After seeking to 2, the next mysqli_fetch_field() returns the email column's metadata.

Re-reading a single column's metadata

A practical use is reading the same column's metadata twice without re-running the query. Because mysqli_fetch_field() advances the cursor, you seek back to reset it:

<?php
$result = mysqli_query($mysqli, "SELECT id, name FROM users");

mysqli_field_seek($result, 1);
$first = mysqli_fetch_field($result);   // reads "name", cursor now at 2

mysqli_field_seek($result, 1);          // rewind to the same column
$again = mysqli_fetch_field($result);   // reads "name" again

printf("%s == %s\n", $first->name, $again->name); // name == name
?>

When would I use this?

In modern code you rarely need it: most applications fetch rows into associative arrays or objects with mysqli_fetch_assoc() and ignore column metadata entirely. mysqli_field_seek() is useful when you are:

• Building a generic tool (a CSV exporter, a schema inspector, a grid renderer) that inspects columns by position.
• Reading one specific column's metadata repeatedly without re-fetching every field with mysqli_fetch_fields().
• Maintaining legacy code that walks result-set metadata column by column.

Conclusion

mysqli_field_seek() repositions the field cursor inside a MySQLi result set so the next mysqli_fetch_field() call returns the column you choose. It works only on column metadata — to jump between data rows, use mysqli_data_seek() instead. While it is uncommon in everyday application code, it is handy for metadata-driven tools and for understanding legacy MySQLi workflows.

Practice