USQL: Ultra Simple Query Language

USQL is the search language used across FiniAC. It works in log search, event log search, event drain filters, and the log search API. The syntax is the same everywhere, but each surface exposes different fields: see Fields by surface.

Syntax

Free-Text

Type any word or phrase to search across all searchable fields. Multiple terms are combined with AND by default.

explosion
Disconnected timeout
"connection timed out"

Negation

Prefix a term with ! or - to exclude results containing it:

!Disconnected
-kicked

Boolean Operators

Combine terms with AND / && and OR / || (case-insensitive):

Rejected AND discord
Connected OR Disconnected

Grouping

Use parentheses to control evaluation order. Without them, AND binds tighter than OR.

(Connected OR Disconnected) AND ExampleUsername

Quoted Phrases

Use double quotes for values with spaces or special characters:

"No Discord account linked"
"connection timed out"

Field Expressions

Target a specific field using field:value syntax. Available in event log search and event drain filters.

event_type:weaponDamage
sender_name:ExamplePlayer
data.script:vMenu

Field names are case-insensitive. Payload keys after data. are not: data.willKill works, data.willkill matches nothing.

Comparison Operators

Operator	Description	Example
:	Field default (exact for event_type, contains for text)	event_type:weaponDamage
=	Exact match	data.entityType=2
!=	Not equal	event_type!=entityCreating
~	Contains (case-insensitive)	payload~vMenu
>	Greater than (numeric)	data.weaponDamage>50
<	Less than (numeric)	data.weaponDamage<100
>= / <=	Greater/less than or equal	data.hitComponent>=20

Numbers and :

In event log search, : on a payload key is a contains match on the value's text: data.hitComponent:2 also matches 12, 20 and 25. Use = for numeric payload fields, or a hash literal for hashes. Event drain filters treat : as an exact match.

Hash Literals

GTA identifies weapons, vehicle and prop models, particle effects and many other assets by a numeric joaat hash, and that is what event payloads store. Wrap a name in backticks and it is hashed for you:

data.weaponType:`weapon_pistol`
data.model:`adder`
data.weaponType!=`weapon_unarmed`

• Names are case-insensitive, matching the game's GET_HASH_KEY.
• A literal matches whether the payload stores the hash signed or unsigned. entityCreating.model is stored signed, weaponDamage.weaponType unsigned, and both work.
• Only :, = and != are allowed, and only on data.* / payload.* fields.
• Works in event log search and event drain filters. The Event Logs page's Weapon, Model and Effect filter inputs also accept a plain name without backticks.

Examples

Free-text (event type, player names, player ID and licenses):

weaponDamage
ExamplePlayer

Search the payload:

payload~vMenu
payload~"\"willKill\":true"
!payload~vMenu

Combine fields and free-text:

event_type:weaponDamage AND ExamplePlayer
(event_type:giveWeaponEvent OR event_type:removeWeaponEvent) AND data.weaponType:`weapon_pistol`
event_type:entityCreating && data.entityType=2 && data.script:vMenu

---

Fields by surface

Logs page

Detection and connection logs. Free-text searches every field below.

Field	Description
type	Log type, e.g. Connected, Noclip
message, data, log	Log text and detection data
name, license, license2, discord, fivem, steam, xbl, live, ip, uid	Player identifiers
filename, screenshot	Source log file and attached media URL

Log search API

The /api/v3/logs endpoint takes the same fields as the Logs page, with two exceptions for API keys:

• ip and identifiers cannot be used as fields, because results never show player IPs.
• A whole IP address cannot be searched as free text, for the same reason.

Words the query parser refuses

For everyone except FiniAC staff, USQL refuses queries containing some SQL keywords, such as admin, view, table, index, config, select or limit, even as plain search text. This applies on the Logs and Event Logs pages and in the API. Search for another word from the same log instead.

Event Logs page

Server events. Free-text searches the event type, player names, player ID and licenses, not the payload.

Field	Default match	Description
event_type	exact	Event type name
sender_name, player_name, target_name	contains	Player names
sender_license, target_license	contains	Rockstar licenses
payload	contains	Raw payload JSON text
data.* / payload.*	contains	A key inside the payload, see Payload keys

Discord and FiveM IDs are not searchable on this page. Use the identifier columns in the results, or an event drain filter.

Event drain filters Enterprise

Event drains evaluate filters against the delivered event object, flattened to dot-notation paths. : is an exact match here.

Event fields:

Field	Description
type	Event type name
event_type	Alias for type
event_time	Event timestamp, YYYY-MM-DD HH:MM:SS in UTC
player_name	Sender name and server ID, e.g. Alpha/30
player_id	Sender server ID

Sender identifiers — access with sender. prefix:

Field	Description
sender.name	Sender player name
sender.license	Rockstar license (40 hex characters)
sender.license2	Secondary license
sender.discord	Discord ID
sender.fivem	FiveM ID
sender.ip	IP address
sender.xbl, sender.live	Xbox Live / Microsoft IDs, rarely populated

Target identifiers — access with target. prefix. Only weaponDamage events have a target; the same keys as sender.* apply.

Position — only entityCreating and explosionEvent carry a position:

Field	Description
position.x, position.y, position.z	Coordinates
pos_x, pos_y, pos_z	Aliases

Event data — access with data. or payload. prefix. See Payload keys.

Payload keys by event type

Event type	Keys
entityCreating	model (hash), entityType (1 ped, 2 vehicle, 3 object), entityPopType, vehicleType (automobile, bike, trailer, boat, heli, train, plane), script, netId, entityId, driver, velocity
weaponDamage	weaponType (hash), weaponDamage, willKill, hitComponent, damageType, silenced, overrideDefaultDamage, damageFlags, hitGlobalId
explosionEvent	explosionType, damageScale, isInvisible, isAudible, cameraShake, ownerNetId, posX, posY, posZ
ptFxEvent	effectHash, assetHash, scale, isOnEntity, entityNetId, posX/posY/posZ, offsetX/offsetY/offsetZ, rotX/rotY/rotZ
giveWeaponEvent, removeWeaponEvent	weaponType (hash)
givePedScriptedTaskEvent	taskId, entityId
fireEvent	The payload is an array of fire records, so it has no keys to filter on. Use payload~ text search instead.

Payloads also contain raw, unnamed game fields (f104, f242, ...). They can be filtered like any other key but their meaning is not documented.

Drain filter examples

Pistol damage from a specific player:

type:weaponDamage && data.weaponType:`weapon_pistol` && sender.discord:123456789012345678

Killing blows only:

type:weaponDamage && data.willKill:true

Vehicles spawned by a menu resource:

type:entityCreating && data.entityType:2 && data.script:vMenu

A specific vehicle model:

type:entityCreating && data.model:`adder`

Entities created inside an area:

type:entityCreating && position.x>100 && position.x<200 && position.y>300 && position.y<400

Any event involving a player, as sender or target:

sender.license:0123456789abcdef0123456789abcdef01234567 || target.license:0123456789abcdef0123456789abcdef01234567