Merge pull request #33563 from WilliamDAssafMSFT/20250320-sys.fn_get_audit_file_v2

v-ccolin · web-flow · commit cb0ce0511168 · 2025-03-31T08:52:44.000+01:00
20250320 add Fabric DW
diff --git a/docs/includes/applies-to-version/asdb-fabricdw.md b/docs/includes/applies-to-version/asdb-fabricdw.md
@@ -0,0 +1,8 @@
+---
+author: WilliamDAssafMSFT
+ms.author: wiassaf
+ms.date: 03/20/2025
+ms.service: sql
+ms.topic: include
+---
+[!INCLUDE [Applies to](../../includes/applies-md.md)] [!INCLUDE [Azure SQL Database](../../includes/applies-to-version/_asdb.md)] [!INCLUDE [Fabric DW](_fabric-dw.md)]
diff --git a/docs/relational-databases/system-functions/sys-fn-get-audit-file-v2-transact-sql.md b/docs/relational-databases/system-functions/sys-fn-get-audit-file-v2-transact-sql.md
@@ -1,10 +1,10 @@
 ---
 title: "sys.fn_get_audit_file_v2 (Transact-SQL)"
 description: "The sys.fn_get_audit_file_v2 system function replaces sys.fn_get_audit_file, and returns information from an audit file created by a server audit in SQL Server."
-author: sravanisaluru
-ms.author: srsaluru
-ms.reviewer: randolphwest
-ms.date: 06/12/2024
+author: WilliamDAssafMSFT
+ms.author: wiassaf
+ms.reviewer: randolphwest, srsaluru, fresantos
+ms.date: 03/21/2025
 ms.service: sql
 ms.subservice: system-objects
 ms.topic: "reference"
@@ -18,19 +18,21 @@ helpviewer_keywords:
   - "fn_get_audit_file_v2 function"
 dev_langs:
   - "TSQL"
-monikerRange: "=azuresqldb-current || >=sql-server-2016 || >=sql-server-linux-2017 || =azuresqldb-mi-current || =azure-sqldw-latest"
+monikerRange: "=azuresqldb-current || =fabric"
 ---
 # sys.fn_get_audit_file_v2 (Transact-SQL)
 
-[!INCLUDE [asdb](../../includes/applies-to-version/asdb.md)]
+[!INCLUDE [asdb-fabricdw](../../includes/applies-to-version/asdb-fabricdw.md)]
 
-The `sys.fn_get_audit_file_v2` system function in [!INCLUDE [ssazure-sqldb](../../includes/ssazure-sqldb.md)] is designed to retrieve audit log data with enhanced efficiency compared to its predecessor, `sys.fn_get_audit_file`. The function introduces time-based filtering at both the file and record levels, providing significant performance improvements, particularly for queries targeting specific time ranges.
-
-> [!IMPORTANT]  
-> `sys.fn_get_audit_file_v2` is currently supported on [!INCLUDE [ssazure-sqldb](../../includes/ssazure-sqldb.md)] only.
+The `sys.fn_get_audit_file_v2` system function is designed to retrieve audit log data with enhanced efficiency compared to its predecessor, `sys.fn_get_audit_file`. The function introduces time-based filtering at both the file and record levels, providing significant performance improvements, particularly for queries targeting specific time ranges.
 
 Returns information from an audit file created by a server audit in [!INCLUDE [ssazure-sqldb](../../includes/ssazure-sqldb.md)]. For more information, see [SQL Server Audit (Database Engine)](../security/auditing/sql-server-audit-database-engine.md).
 
+For information on setting up Azure SQL Database auditing, see [Get Started with SQL Database auditing](/azure/sql-database/sql-database-auditing?view=azuresql-db&preserve-view=true).
+
+For information on setting up Fabric Data Warehouse auditing, see [SQL Audit Logs in Fabric Data Warehouse](/fabric/data-warehouse/sql-audit-logs).
+
+
 :::image type="icon" source="../../includes/media/topic-link-icon.svg" border="false"::: [Transact-SQL syntax conventions](../../t-sql/language-elements/transact-sql-syntax-conventions-transact-sql.md)
 
 ## Syntax
@@ -47,6 +49,8 @@ fn_get_audit_file_v2 ( file_pattern
 
 #### *file_pattern*
 
+**Applies to:** [!INCLUDE [ssazure-sqldb](../../includes/ssazure-sqldb.md)] only
+
 Specifies the directory or path and file name for the audit file set to be read. *file_pattern* is **nvarchar(260)**.
 
 Passing a path without a file name pattern generates an error.
@@ -59,12 +63,16 @@ This argument is used to specify a blob URL (including the storage endpoint and
 
 #### *initial_file_name*
 
+**Applies to:** [!INCLUDE [ssazure-sqldb](../../includes/ssazure-sqldb.md)] only
+
 Specifies the path and name of a specific file in the audit file set to start reading audit records from. *initial_file_name* is **nvarchar(260)**.
 
 The *initial_file_name* argument must contain valid entries or must contain either the `default` or `NULL` value.
 
 #### *audit_record_offset*
 
+**Applies to:** [!INCLUDE [ssazure-sqldb](../../includes/ssazure-sqldb.md)] only
+
 Specifies a known location with the file specified for the *initial_file_name*. When this argument is used, the function starts reading at the first record of the buffer immediately following the specified offset.
 
 The *audit_record_offset* argument must contain valid entries or must contain either the `default` or `NULL` value. *audit_record_offset* is **bigint**.
@@ -110,28 +118,28 @@ The following table describes the audit file content returned by this function.
 | `statement` | **nvarchar(4000)** | Transact-SQL statement if it exists. Nullable. Returns `NULL` if not applicable. |
 | `additional_information` | **nvarchar(4000)** | Unique information that only applies to a single event is returned as XML. A few auditable actions contain this kind of information.<br /><br />One level of T-SQL stack is displayed in XML format for actions that have T-SQL stack associated with them. The XML format is: `<tsql_stack><frame nest_level = '%u' database_name = '%.*s' schema_name = '%.*s' object_name = '%.*s' /></tsql_stack>`<br /><br />`frame nest_level` indicates the current nesting level of the frame. The module name is represented in three part format (`database_name`, `schema_name`, and `object_name`). The module name is parsed to escape invalid XML characters like `<`, `>`, `/`, `_x`. They're escaped as `_xHHHH_`. The `HHHH` stands for the four-digit hexadecimal UCS-2 code for the character. Nullable. Returns `NULL` when there's no additional information reported by the event. |
 | `file_name` | **varchar(260)** | The path and name of the audit log file that the record came from. Not nullable. |
-| `audit_file_offset` | **bigint** | The buffer offset in the file that contains the audit record. Not nullable.<br /><br />**Applies to**: SQL Server only |
-| `user_defined_event_id` | **smallint** | User defined event ID passed as an argument to `sp_audit_write`. `NULL` for system events (default) and non-zero for user-defined event. For more information, see [sp_audit_write (Transact-SQL)](../../relational-databases/system-stored-procedures/sp-audit-write-transact-sql.md).<br /><br />**Applies to**: [!INCLUDE [ssSQL11](../../includes/sssql11-md.md)] and later, Azure SQL Database, and SQL Managed Instance |
-| `user_defined_information` | **nvarchar(4000)** | Used to record any extra information the user wants to record in audit log by using the `sp_audit_write` stored procedure.<br /><br />**Applies to**: [!INCLUDE [ssSQL11](../../includes/sssql11-md.md)] and later versions, Azure SQL Database, and SQL Managed Instance |
+| `audit_file_offset` | **bigint** | The buffer offset in the file that contains the audit record. Not nullable. |
+| `user_defined_event_id` | **smallint** | User defined event ID passed as an argument to `sp_audit_write`. `NULL` for system events (default) and non-zero for user-defined event. For more information, see [sp_audit_write (Transact-SQL)](../../relational-databases/system-stored-procedures/sp-audit-write-transact-sql.md). |
+| `user_defined_information` | **nvarchar(4000)** | Used to record any extra information the user wants to record in audit log by using the `sp_audit_write` stored procedure.|
 | `audit_schema_version` | **int** | Always `1`. |
-| `sequence_group_id` | **varbinary** | Unique identifier.<br /><br />**Applies to**: [!INCLUDE [sssql16-md](../../includes/sssql16-md.md)] and later versions |
-| `transaction_id` | **bigint** | Unique identifier to identify multiple audit events in one transaction.<br /><br />**Applies to**: [!INCLUDE [sssql16-md](../../includes/sssql16-md.md)] and later versions |
-| `client_ip` | **nvarchar(128)** | Source IP of the client application.<br /><br />**Applies to**: [!INCLUDE [sssql17-md](../../includes/sssql17-md.md)] and later versions, and Azure SQL Database |
-| `application_name` | **nvarchar(128)** | Name of client application that executed the statement that caused the audit event.<br /><br />**Applies to**: [!INCLUDE [sssql17-md](../../includes/sssql17-md.md)] and later versions, and Azure SQL Database |
-| `duration_milliseconds` | **bigint** | Query execution duration in milliseconds.<br /><br />**Applies to**: Azure SQL Database and SQL Managed Instance |
-| `response_rows` | **bigint** | Number of rows returned in the result set.<br /><br />**Applies to**: Azure SQL Database and SQL Managed Instance |
-| `affected_rows` | **bigint** | Number of rows affected by the executed statement.<br /><br />**Applies to**: Azure SQL Database only |
-| `connection_id` | **uniqueidentifier** | ID of the connection in the server.<br /><br />**Applies to**: Azure SQL Database and SQL Managed Instance |
-| `data_sensitivity_information` | **nvarchar(4000)** | Information types and sensitivity labels returned by the audited query, based on the classified columns in the database. Learn more about [Azure SQL Database data discover and classification](/azure/sql-database/sql-database-data-discovery-and-classification).<br /><br />**Applies to**: Azure SQL Database only |
+| `sequence_group_id` | **varbinary** | Unique identifier.<|
+| `transaction_id` | **bigint** | Unique identifier to identify multiple audit events in one transaction. |
+| `client_ip` | **nvarchar(128)** | Source IP of the client application. |
+| `application_name` | **nvarchar(128)** | Name of client application that executed the statement that caused the audit event.|
+| `duration_milliseconds` | **bigint** | Query execution duration in milliseconds. |
+| `response_rows` | **bigint** | Number of rows returned in the result set.< |
+| `affected_rows` | **bigint** | Number of rows affected by the executed statement.|
+| `connection_id` | **uniqueidentifier** | ID of the connection in the server. |
+| `data_sensitivity_information` | **nvarchar(4000)** | Information types and sensitivity labels returned by the audited query, based on the classified columns in the database. Learn more about [Azure SQL Database data discover and classification](/azure/sql-database/sql-database-data-discovery-and-classification).|
 | `host_name` | **nvarchar(128)** | Host Name of the client machine. |
 | `session_context` | **nvarchar(4000)** | The key-value pairs that are a part of the current session context. |
 | `client_tls_version` | **bigint** | Minimum TLS version supported by the client. |
 | `client_tls_version_name` | **nvarchar(128)** | Minimum TLS version supported by the client. |
 | `database_transaction_id` | **bigint** | Transaction ID of the current transaction in the current session. |
-| `ledger_start_sequence_number` | **bigint** | The sequence number of an operation within a transaction that created a row version.<br /><br />**Applies to:** Azure SQL Database only |
-| `external_policy_permissions_checked` | **nvarchar(4000)** | Information related to the external authorization permission check, when an audit event is generated, and Purview external authorization policies are evaluated.<br /><br />**Applies to:** Azure SQL Database only |
-| `obo_middle_tier_app_id` | **varchar(120)** | The application ID of the middle tier application that connects to Azure SQL Database using on-behalf-of (OBO) access. Nullable. Returns `NULL` if the request isn't made using OBO access.<br /><br />**Applies to**: Azure SQL Database only |
-| `is_local_secondary_replica` | **bit** | `True` if the audit record originates from a read-only local secondary replica, `False` otherwise.<br /><br />**Applies to:** Azure SQL Database only |
+| `ledger_start_sequence_number` | **bigint** | The sequence number of an operation within a transaction that created a row version.|
+| `external_policy_permissions_checked` | **nvarchar(4000)** | Information related to the external authorization permission check, when an audit event is generated, and Purview external authorization policies are evaluated.|
+| `obo_middle_tier_app_id` | **varchar(120)** | The application ID of the middle tier application that connects using on-behalf-of (OBO) access. Nullable. Returns `NULL` if the request isn't made using OBO access.|
+| `is_local_secondary_replica` | **bit** | `True` if the audit record originates from a read-only local secondary replica, `False` otherwise.|
 
 ## Improvements over sys.fn_get_audit_file
 
@@ -151,16 +159,18 @@ The performance improvements are primarily dependent on the rollover time of the
 
 - **Scalability**: Helps maintain performance even as the number of databases increases, though the net improvement might be less pronounced in environments with a high number of databases.
 
-For information on setting up Azure SQL Database auditing, see [Get Started with SQL Database auditing](/azure/sql-database/sql-database-auditing).
-
 ## Remarks
 
-- If the *file_pattern* argument passed to `fn_get_audit_file_v2` references a path or file that doesn't exist, or if the file isn't an audit file, the `MSG_INVALID_AUDIT_FILE` error message is returned.
+If the *file_pattern* argument passed to `fn_get_audit_file_v2` references a path or file that doesn't exist, or if the file isn't an audit file, the `MSG_INVALID_AUDIT_FILE` error message is returned.
+
+The `fn_get_audit_file_v2` function can't be used when the audit is created with the `APPLICATION_LOG`, `SECURITY_LOG`, or `EXTERNAL_MONITOR` options.
 
-- `fn_get_audit_file_v2` can't be used when the audit is created with the `APPLICATION_LOG`, `SECURITY_LOG`, or `EXTERNAL_MONITOR` options.
+Currently in Fabric Data Warehouse, you cannot access individual files, only the audit folder. The following arguments are not supported for SQL Audit on a warehouse item: `file_pattern`, `initial_file_name`, `audit_record_offset`.
 
 ## Permissions
 
+### Permissions required in Azure SQL Database
+
 Requires the `CONTROL DATABASE` permission.
 
 - Server admins can access audit logs of all databases on the server.
@@ -169,14 +179,38 @@ Requires the `CONTROL DATABASE` permission.
 
 - Blobs that don't meet the above criteria are skipped (a list of skipped blobs is displayed in the query output message). The function returns logs only from blobs for which access is allowed.
 
+### Permissions required in Fabric Data Warehouse
+
+Users must have the Fabric item `Audit` permission. For more information, see [Permissions](/fabric/data-warehouse/sql-audit-logs#permissions).
+
 ## Examples
 
+### A. View SQL audit logs for Azure SQL Database
+
 This example retrieves audit logs from a specific Azure Blob Storage location, filtering records between `2023-11-17T08:40:40Z` and `2023-11-17T09:10:40Z`.
 
 ```sql
 SELECT *
 FROM sys. fn_get_audit_file_v2(
-    'https://yourstorageaccount.blob.core.windows.net/sqldbauditlogs/server_name/database_name/SqlDbAuditing_ServerAudit/',
+    'https://<storage_account>.blob.core.windows.net/sqldbauditlogs/server_name/database_name/SqlDbAuditing_ServerAudit/',
+    DEFAULT,
+    DEFAULT,
+    '2023-11-17T08:40:40Z',
+    '2023-11-17T09:10:40Z')
+```
+
+### B. View SQL audit logs for Fabric Data Warehouse
+
+This example retrieves audit logs from OneLake folder aligned with the current workspace and warehouse, filtering records between `2023-11-17T08:40:40Z` and `2023-11-17T09:10:40Z`.
+
+In the Fabric portal, retrieve your `workspaceID` and `warehouseID`:
+- `<workspaceID>`: Visit your workspace in the Fabric portal. Find the workspace GUID in the URL after the `/groups/` section, or by running `SELECT @@SERVERNAME` in an existing warehouse. If your `/groups/` URL is followed by `/me/`, you're using the default workspace, and currently SQL Audit for Fabric Data Warehouse is not supported in the default workspace. 
+- `<warehouseID>`: Visit your warehouse in the Fabric portal. Find the warehouse ID in the URL after the `/warehouses/` section. 
+
+```sql
+SELECT *
+FROM sys. fn_get_audit_file_v2(
+    'https://onelake.blob.fabric.microsoft.com/{workspaceId}/{warehouseId}/Audit/sqldbauditlogs/',
     DEFAULT,
     DEFAULT,
     '2023-11-17T08:40:40Z',
@@ -213,3 +247,5 @@ Transact-SQL:
 - [sys.dm_audit_class_type_map (Transact-SQL)](../system-dynamic-management-views/sys-dm-audit-class-type-map-transact-sql.md)
 - [sys.server_audits (Transact-SQL)](../system-catalog-views/sys-server-audits-transact-sql.md)
 - [sys.server_file_audits (Transact-SQL)](../system-catalog-views/sys-server-file-audits-transact-sql.md)
+- [Get Started with SQL Database auditing](/azure/sql-database/sql-database-auditing?view=azuresql-db&preserve-view=true)
+- [SQL Audit Logs in Fabric Data Warehouse](/fabric/data-warehouse/sql-audit-logs)
