查詢語法

Osprey 使用 SML 進行查詢。SML 全名為 Some Madeup Language，是加入額外限制的 Python 子集。查詢會比對 Features，也就是 Rules 從每個 event 擷取的具名值，其中包含 Entities 與 Labels。若尚不熟悉這些術語，請先閱讀基本概念。

基本比較

EventType == "create_post"
UserId == 12345
MessageText != None

組合條件

# AND: all conditions must match
EventType == "user_login" and LoginAttempts >= 3

# OR: any condition may match
(UserId == 123) or (UserId == 456)

# in: match any value in a list
EventType in ["create_post", "send_message"]

查詢函式

查詢支援一組固定且數量不多的 built-in functions。Rules 使用的 UDFs 可以透過 Plugins 擴充，但查詢函式不會隨著新增 Plugins 增加。

• RegexMatch(target=..., pattern=...)　使用 regular expression 比對 Feature
• DidAddLabel(...) 與 DidRemoveLabel(...)　比對新增或移除 Label 的 Events，詳見 Label 查詢
• DidDeclareVerdict(...)　比對宣告 Verdict 的 Events

# Regex match against a feature
RegexMatch(target=MessageText, pattern="(buy|sell|deal)")

Note

查詢只能使用上述函式。UDF Registry 會列出所有 UDFs，但大多數只能用於 Rules。若在查詢中使用這些 UDFs，目前會發生沒有可見訊息的 500 error。

Label 查詢

查詢介面搜尋的是 Events，不是 Entity 目前的狀態，因此無法在此使用 HasLabel()。請改用 DidAddLabel()，比對曾新增 Label 的 Events。

# Find events that added a specific label
DidAddLabel(entity_type="User", label_name="likely_spammer")
DidAddLabel(entity_type="IpAddress", label_name="suspicious")

查詢範例

# Suspicious login attempts
EventType == "user_login" and LoginAttempts >= 5

# Posts matching a pattern
EventType == "create_post" and RegexMatch(target=PostContent, pattern="urgent")

# Users who were flagged
DidAddLabel(entity_type="User", label_name="flagged")

# Complex: messages matching a pattern, from users without a verified label
EventType == "send_message" and
RegexMatch(target=MessageText, pattern="(click|link|urgent)") and
not DidAddLabel(entity_type="User", label_name="verified")

查詢可能包含 user IDs、IP addresses、電子郵件、事件內容或調查策略。分享 URL、匯出結果及保存查詢時，應依最小必要原則處理，避免將敏感參數帶入不受控的記錄或通訊管道。