LOGIN_HISTORY , LOGIN_HISTORY_BY_USER¶
The LOGIN_HISTORY family of table functions can be used to query login attempts by Snowflake users along various dimensions:
- LOGIN_HISTORY returns login events within a specified time range.
- LOGIN_HISTORY_BY_USER returns login events of a specified user within a specified time range.
Each function is optimized for querying along the specified dimension. The results can be further filtered using SQL predicates.
These functions return login activity within the last 7 days.
LOGIN_HISTORY( [ TIME_RANGE_START => <constant_expr> ] [, TIME_RANGE_END => <constant_expr> ] [, RESULT_LIMIT => <num> ] ) LOGIN_HISTORY_BY_USER( [ USER_NAME => '<string>' ] [, TIME_RANGE_START => <constant_expr> ] [, TIME_RANGE_END => <constant_expr> ] [, RESULT_LIMIT => <num> ] )
All the arguments are optional.
TIME_RANGE_START => constant_expr, .
TIME_RANGE_END => constant_expr
Time range (in TIMESTAMP_LTZ format), within the last 7 days, in which the login event occurred.
TIME_RANGE_ENDis not specified, the function returns the most recent login events.
If the time range does not fall within the last 7 days, an error is returned.
USER_NAME => 'string'
Applies only to LOGIN_HISTORY_BY_USER
A string specifying a user name or CURRENT_USER. Only login events for the specified user are returned. Note that the login name must be enclosed in single quotes. Also, if the login name contains any spaces, mixed-case characters, or special characters, the name must be double-quoted within the single quotes (e.g.
RESULT_LIMIT => num
A number specifying the maximum number of rows returned by the function.
If the number of matching rows is greater than this limit, the login events with the most recent timestamp are returned, up to the specified limit.
- When calling an Information Schema table function, the session must have an INFORMATION_SCHEMA schema in use or the function name must be fully-qualified. For more details, see Information Schema.
The function returns the following columns:
|Column Name||Data Type||Description|
|EVENT_TIMESTAMP||TIMESTAMP_LTZ||Time of the event occurrence.|
|EVENT_ID||NUMBER||Event’s unique id.|
|EVENT_TYPE||TEXT||Event type, such as LOGIN for authentication events.|
|USER_NAME||TEXT||User associated with this event.|
|CLIENT_IP||TEXT||IP address where the request originated from.|
|REPORTED_CLIENT_TYPE||TEXT||Reported type of the client software, such as JDBC_DRIVER, ODBC_DRIVER, etc. This information is not authenticated.|
|REPORTED_CLIENT_VERSION||TEXT||Reported version of the client software. This information is not authenticated.|
|FIRST_AUTHENTICATION_FACTOR||TEXT||Method used to authenticate the user (the first factor, if using multi factor authentication).|
|SECOND_AUTHENTICATION_FACTOR||TEXT||The second factor, if using multi factor authentication, or NULL otherwise.|
|IS_SUCCESS||TEXT||Whether the user’s request was successful or not.|
|ERROR_CODE||NUMBER||Error code, if the request was not successful.|
|ERROR_MESSAGE||TEXT||Error message returned to the user, if the request was not successful.|
|RELATED_EVENT_ID||NUMBER||Reserved for future use.|
For details about the error codes/messages for login attempts that were unsuccessful due to invalid SAML responses, see SAML Error Codes.
Retrieve up to the last 100 login events of the current user:
select * from table(information_schema.login_history_by_user()) order by event_timestamp;
Retrieve up to the last 1000 login events of the specified user:
select * from table(information_schema.login_history_by_user('USER1', result_limit=>1000)) order by event_timestamp;
Retrieve up to 100 login events of every user your current role is allowed to monitor (or every user in your account, if your current role is ACCOUNTADMIN) in the last hour:
select * from table(information_schema.login_history(dateadd('hours',-1,current_timestamp()),current_timestamp())) order by event_timestamp;