sqlsrv_num_rows — Funktion · PHP-Referenz

Signatur

sqlsrv_num_rows(resource $stmt): int|false

Beschreibung

sqlsrv_num_rows() ermittelt die Gesamtanzahl der Zeilen, die ein SELECT-Statement zurückgeliefert hat. Die Funktion arbeitet mit dem sqlsrv-Erweiterungsmodul, das für die Verbindung zu Microsoft SQL Server und Azure SQL eingesetzt wird.

Wichtig: Die Funktion liefert nur dann ein sinnvolles Ergebnis, wenn das Statement mit einem scrollbaren Cursor ausgeführt wurde. Standardmäßig verwendet sqlsrv_query() und sqlsrv_execute() einen Forward-Only-Cursor, bei dem sqlsrv_num_rows() false zurückgibt. Um die Zeilenanzahl zu erhalten, muss beim Ausführen der Abfrage explizit ein statischer, dynamischer oder keyset-basierter Cursor angegeben werden (z. B. SQLSRV_CURSOR_STATIC).

Ein scrollbarer Cursor erfordert, dass der SQL Server alle Ergebnisse zunächst in den Speicher lädt, bevor die Anwendung sie verarbeiten kann. Das kann bei großen Ergebnismengen zu erhöhtem Speicherverbrauch führen. In solchen Fällen sollte man abwägen, ob die Zeilenanzahl wirklich vorab benötigt wird, oder ob man sie alternativ über eine COUNT(*)-Abfrage ermittelt.

Die Funktion gibt bei Erfolg die Anzahl der Zeilen als nicht-negativen Integer zurück. Im Fehlerfall — etwa wenn kein scrollbarer Cursor gesetzt wurde — wird false zurückgegeben.

Parameter

Name	Typ	Default	Beschreibung
$stmt Pflicht	resource		Eine Statement-Ressource, die durch `sqlsrv_query()` oder `sqlsrv_execute()` erzeugt wurde. Das Statement muss mit einem scrollbaren Cursor erstellt worden sein, damit die Funktion die Zeilenanzahl korrekt zurückgeben kann.

Rückgabewert

Typ

int|false

Beschreibung

Gibt die Anzahl der Zeilen im Ergebnis als Integer zurück. Wurde das Statement ohne scrollbaren Cursor ausgeführt oder ist ein Fehler aufgetreten, wird false zurückgegeben.

Beispiele

Zeilenanzahl mit statischem Cursor ermitteln

<?php
$serverName = "localhost";
$connectionInfo = [
    "Database" => "AdventureWorks",
    "UID"      => "sa",
    "PWD"      => "geheimes_passwort"
];

$conn = sqlsrv_connect($serverName, $connectionInfo);
if ($conn === false) {
    die(print_r(sqlsrv_errors(), true));
}

$sql  = "SELECT ProductID, Name FROM Production.Product WHERE ListPrice > 100";
// Statischen Cursor angeben, damit sqlsrv_num_rows() funktioniert
$opts = ["Scrollable" => SQLSRV_CURSOR_STATIC];
$stmt = sqlsrv_query($conn, $sql, [], $opts);

if ($stmt === false) {
    die(print_r(sqlsrv_errors(), true));
}

$rowCount = sqlsrv_num_rows($stmt);
if ($rowCount === false) {
    echo "Fehler beim Ermitteln der Zeilenanzahl.\n";
} else {
    echo "Anzahl der gefundenen Produkte: " . $rowCount . "\n";
}

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);

Anzahl der gefundenen Produkte: 397

Fehlschlag bei Forward-Only-Cursor (Standardverhalten)

<?php
$serverName = "localhost";
$connectionInfo = [
    "Database" => "TestDB",
    "UID"      => "sa",
    "PWD"      => "geheimes_passwort"
];

$conn = sqlsrv_connect($serverName, $connectionInfo);
if ($conn === false) {
    die(print_r(sqlsrv_errors(), true));
}

// Kein Cursor angegeben: Standard ist FORWARD_ONLY
$sql  = "SELECT id, username FROM users";
$stmt = sqlsrv_query($conn, $sql);

$rowCount = sqlsrv_num_rows($stmt);
if ($rowCount === false) {
    echo "sqlsrv_num_rows() gibt false zurück, da kein scrollbarer Cursor verwendet wurde.\n";
    echo "Lösung: SQLSRV_CURSOR_STATIC beim Ausführen des Statements angeben.\n";
} else {
    echo "Zeilen: " . $rowCount . "\n";
}

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);

sqlsrv_num_rows() gibt false zurück, da kein scrollbarer Cursor verwendet wurde. Lösung: SQLSRV_CURSOR_STATIC beim Ausführen des Statements angeben.

// Wichtig · Fallstricke

Cursor-Typ entscheidend: sqlsrv_num_rows() funktioniert nur mit scrollbaren Cursorn. Gültige Optionen für den "Scrollable"-Schlüssel sind SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, SQLSRV_CURSOR_KEYSET und SQLSRV_CURSOR_CLIENT_BUFFERED. Der Standard (SQLSRV_CURSOR_FORWARD) liefert false.

Speicherverbrauch: Scrollbare Cursor laden alle Ergebniszeilen in den Speicher des Clients oder Servers. Bei sehr großen Ergebnismengen (Hunderttausende von Zeilen) kann dies zu Speicher- oder Performance-Problemen führen. Eine SELECT COUNT(*) FROM ...-Abfrage ist in solchen Fällen die effizientere Alternative.

Nur für SELECT-Abfragen: Bei DML-Statements (INSERT, UPDATE, DELETE) sollte stattdessen sqlsrv_rows_affected() verwendet werden, um die Anzahl der betroffenen Zeilen zu ermitteln.

Siehe auch

sqlsrv_query sqlsrv_execute sqlsrv_rows_affected sqlsrv_fetch_array sqlsrv_errors sqlsrv_free_stmt