fetch_field_direct

A função mysqli_fetch_field_direct() obtém os metadados de uma única coluna em um conjunto de resultados, selecionada diretamente pela sua posição numérica. Os metadados descrevem a própria coluna — seu nome, a tabela de onde veio, seu tipo de dado, comprimento e flags — em vez dos valores de linha armazenados nela. Esta página aborda a sintaxe, o object que ela retorna, um exemplo completo e quando utilizá-la em vez das funções relacionadas.

Sintaxe

mysqli_fetch_field_direct(mysqli_result $result, int $index): object|false

No estilo orientado a objetos, a mesma chamada é $result->fetch_field_direct($index).

• $result — um object mysqli_result retornado por uma consulta como mysqli_query() (ou mysqli_store_result() / mysqli_use_result()).
• $index — a posição baseada em zero da coluna desejada. A primeira coluna é 0, a segunda é 1, e assim por diante. Um índice fora do intervalo faz a função retornar false.

O valor de retorno é um object cujas propriedades descrevem a coluna. Se o índice for inválido, a função retorna false.

O object de campo

O object retornado expõe as seguintes propriedades:

Como usar mysqli_fetch_field_direct()

Passe um conjunto de resultados válido e o índice da coluna cujos metadados você precisa:

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

if (!$mysqli) {
    die("Connection failed: " . mysqli_connect_error());
}

$query = "SELECT * FROM my_table";
$result = mysqli_query($mysqli, $query);

if ($result) {
    // Metadata for the second column (index 1, zero-based)
    $field = mysqli_fetch_field_direct($result, 1);

    printf("Name:   %s\n", $field->name);
    printf("Table:  %s\n", $field->table);
    printf("Type:   %d\n", $field->type);   // integer type constant
    printf("Length: %d\n", $field->length);

    mysqli_free_result($result);
} else {
    echo "Query failed: " . mysqli_error($mysqli);
}

mysqli_close($mysqli);
?>

Aqui nos conectamos com mysqli_connect() e nos protegemos contra uma conexão falha. Executamos uma consulta com mysqli_query() e, se ela for bem-sucedida, chamamos mysqli_fetch_field_direct($result, 1) para ler os metadados da segunda coluna (lembrando que o índice é baseado em zero). Imprimimos algumas de suas propriedades e liberamos o conjunto de resultados ao terminar. Como type é uma constante inteira em vez de um nome legível, formatamos com %d.

Lendo a constante de tipo

A propriedade type é uma das constantes MYSQLI_TYPE_* — um inteiro, não uma palavra como "varchar". Para transformá-la em algo legível, mapeie as constantes manualmente:

<?php
$types = [
    MYSQLI_TYPE_DECIMAL   => 'DECIMAL',
    MYSQLI_TYPE_LONG      => 'INT',
    MYSQLI_TYPE_VAR_STRING => 'VARCHAR',
    MYSQLI_TYPE_STRING    => 'CHAR',
    MYSQLI_TYPE_DATETIME  => 'DATETIME',
];

$field = mysqli_fetch_field_direct($result, 0);
echo $types[$field->type] ?? "Unknown ({$field->type})";
?>

Quando usar

Use mysqli_fetch_field_direct() quando você já sabe qual coluna deseja e pode endereçá-la por índice — por exemplo, ao construir um renderizador de tabela genérico ou validar que a segunda coluna realmente é do tipo esperado.

• Para percorrer os metadados de cada coluna individualmente, use mysqli_fetch_field(), que avança um ponteiro interno a cada chamada.
• Para obter os metadados de todas as colunas de uma vez como um array, use mysqli_fetch_fields().
• Para buscar os dados da linha em vez dos metadados da coluna, use mysqli_fetch_assoc(), mysqli_fetch_row() ou mysqli_fetch_object().
• Para saber quantas colunas o resultado possui antes de indexá-las, use mysqli_field_count().

Conclusão

mysqli_fetch_field_direct() fornece os metadados de uma coluna endereçada diretamente pelo seu índice baseado em zero, retornando um object com o nome, tabela, tipo, comprimento e flags da coluna — ou false para um índice fora do intervalo. Ela se combina naturalmente com as outras funções mysqli_fetch_field* quando você precisa inspecionar a estrutura de um conjunto de resultados em vez de suas linhas.

Prática