Class QueryGuardPolicy

Namespace: QueryGuard

Assembly: QueryGuard.Core.dll

A named set of query budgets and thresholds evaluated against a completed session.

public sealed class QueryGuardPolicy

Inheritance: object

QueryGuardPolicy

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

Examples

var policy = QueryGuardPolicy.Create("companies")
    .WithMaxQueries(20, QueryGuardSeverity.Warning)
    .WithMaxOccurrencesPerFingerprint(5, QueryGuardSeverity.Failure);

Remarks

A policy is immutable. Each With… method returns a new instance, so a policy can be safely shared as a singleton, captured in a field, and reused across concurrent requests.

Severity is per rule rather than per policy: warning on a total-count budget while failing on a per-fingerprint budget is the most useful default combination, because the second rule is the one that actually catches an N+1 regression.

Every limit is opt-in and starts unset, with one exception: the repeated-query threshold defaults to DefaultRepeatedQueryThreshold so QueryGuard has something useful to say without configuration. It produces a warning, never a failure.

Fields

DefaultRepeatedQueryThreshold: The number of occurrences of one fingerprint at which QueryGuard warns by default.

Properties

Allowlist: Gets the intentional repetitions this policy has recorded, each with its reason.

CountedKinds: Gets the command kinds counted toward budgets. Defaults to reader and scalar commands.

MaxDuplicateGroups: Gets the maximum number of fingerprints allowed to reach RepeatedQueryThreshold, or null when unlimited.

MaxDuplicateGroupsSeverity: Gets the severity applied when MaxDuplicateGroups is exceeded.

MaxOccurrencesPerFingerprint: Gets the maximum number of occurrences allowed for any single fingerprint, or null when unlimited.

MaxOccurrencesPerFingerprintSeverity: Gets the severity applied when MaxOccurrencesPerFingerprint is exceeded.

MaxQueries: Gets the maximum number of counted commands allowed in the session, or null when unlimited.

MaxQueriesSeverity: Gets the severity applied when MaxQueries is exceeded.

MaxTotalDuration: Gets the maximum summed command duration allowed, or null when unlimited.

MaxTotalDurationSeverity: Gets the severity applied when MaxTotalDuration is exceeded.

Name: Gets the policy name. It appears in every finding and report, so it should identify the route or test it guards.

RepeatedQueryThreshold: Gets the number of occurrences of a single fingerprint that produces a repeated-query candidate warning.

SlowQuerySeverity: Gets the severity applied when a command exceeds SlowQueryThreshold.

SlowQueryThreshold: Gets the duration above which a single command is reported as slow, or null when disabled.

Methods

Allow(QueryGuardAllowlistEntry): Adds an allowlist entry.

AllowFingerprint(string, string): Records that a specific fingerprint's repetition is intentional.

AllowQueryTag(string, string): Records that any query carrying a given tag repeats intentionally.

Counts(QueryCommandKind): Determines whether a command of the given kind counts toward this policy's budgets.

Create(string): Creates a policy with default thresholds and no budgets.

FindAllowlistReason(string?, IReadOnlyList<string>?): Finds the reason a finding is allowlisted, if it is.

ToString(): Returns a string that represents the current object.

WithCountedKinds(params QueryCommandKind[]): Sets which command kinds count toward budgets.

WithMaxDuplicateGroups(int, QueryGuardSeverity): Limits how many fingerprints may reach RepeatedQueryThreshold.

WithMaxOccurrencesPerFingerprint(int, QueryGuardSeverity): Limits how many times any single fingerprint may occur.

WithMaxQueries(int, QueryGuardSeverity): Limits how many counted commands the session may execute.

WithMaxTotalDuration(TimeSpan, QueryGuardSeverity): Limits the summed duration of counted commands.

WithName(string): Returns a copy of this policy under a different name, keeping every configured limit.

WithRepeatedQueryThreshold(int): Sets how many occurrences of one fingerprint produce a repeated-query candidate warning.

WithSlowQueryThreshold(TimeSpan, QueryGuardSeverity): Reports any single command slower than the given threshold.