optimize

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 11, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// LoweringProjectionPruning identifies removal of traversal fields that downstream clauses do not consume.
	LoweringProjectionPruning = "ProjectionPruning"

	// LoweringLatePathMaterialization identifies deferral of path hydration until a consumer requires it.
	LoweringLatePathMaterialization = "LatePathMaterialization"

	// LoweringExpandIntoDetection identifies traversal steps whose two endpoints are already bound.
	LoweringExpandIntoDetection = "ExpandIntoDetection"

	// LoweringTraversalDirection identifies selection of the lower-cost logical traversal direction.
	LoweringTraversalDirection = "TraversalDirectionSelection"

	// LoweringShortestPathStrategy identifies unidirectional or bidirectional shortest-path selection.
	LoweringShortestPathStrategy = "ShortestPathStrategySelection"

	// LoweringShortestPathFilter identifies materialization of reusable shortest-path endpoint filters.
	LoweringShortestPathFilter = "ShortestPathFilterMaterialization"

	// LoweringLimitPushdown identifies limits moved into a traversal or shortest-path harness.
	LoweringLimitPushdown = "LimitPushdown"

	// LoweringExpansionSuffixPushdown identifies fixed-suffix predicates moved closer to variable expansion.
	LoweringExpansionSuffixPushdown = "ExpansionSuffixPushdown"

	// LoweringPredicatePlacement identifies attachment of predicates to the earliest safe traversal step.
	LoweringPredicatePlacement = "PredicatePlacement"

	// LoweringCountStoreFastPath identifies count queries satisfied directly from graph statistics.
	LoweringCountStoreFastPath = "CountStoreFastPath"

	// LoweringCollectIDMembership identifies membership checks rewritten over collected scalar IDs.
	LoweringCollectIDMembership = "CollectIDMembership"

	// LoweringAggregateTraversalCount identifies traversal counts lowered without materializing result rows.
	LoweringAggregateTraversalCount = "AggregateTraversalCount"

	// LoweringExactRangeExpansion identifies short exact ranges expanded into fixed traversal steps.
	LoweringExactRangeExpansion = "ExactRangeExpansion"

	// LoweringPathRelationshipPredicate identifies relationship quantifiers attached to path state.
	LoweringPathRelationshipPredicate = "PathRelationshipPredicate"

	// LoweringFieldRequirements identifies analysis that records which representation each binding consumer needs.
	LoweringFieldRequirements = "FieldRequirements"

	// LoweringShortestPathExecutor identifies selection of a physical shortest-path executor.
	LoweringShortestPathExecutor = "ShortestPathExecutorDecision"

	// LoweringExpansionSearchStrategy identifies selection of a physical variable-expansion search strategy.
	LoweringExpansionSearchStrategy = "ExpansionSearchStrategyDecision"

	// LoweringEndpointResolution identifies planned bounded endpoint-resolution analysis.
	LoweringEndpointResolution = "EndpointResolutionDecision"

	// LoweringTraversalPredicateClassification identifies planned traversal-predicate locality analysis.
	LoweringTraversalPredicateClassification = "TraversalPredicateClassificationDecision"
)
View Source 
const (
	// ShortestPathPolicyASPI1GuardedV1 identifies the bounded inline
	// predecessor-DAG candidate with an exact A1 fallback.
	ShortestPathPolicyASPI1GuardedV1 = "asp-i1-guarded-v1"

	// ShortestPathPolicyI1CanonicalGuardedV1 identifies the bounded inline
	// canonical-witness candidate with an exact compact S4 fallback.
	ShortestPathPolicyI1CanonicalGuardedV1 = "sp-i1-canonical-guarded-v1"

	// ShortestPathPolicyI2DistanceGuardedV1 identifies reverse-physical inline
	// distance discovery with independent state/frontier gates and S4 fallback.
	ShortestPathPolicyI2DistanceGuardedV1 = "sp-i2-distance-guarded-v1"

	// ShortestPathPolicyI2DistanceGuardedV2 identifies the independently
	// qualified tail-stabilized generation. It does not alias V1 evidence.
	ShortestPathPolicyI2DistanceGuardedV2 = "sp-i2-distance-guarded-v2"

	// ShortestPathI2QualifiedStateLimit is the immutable total-state ceiling
	// preregistered by the SP-I2 production-form protocol and policy seam.
	ShortestPathI2QualifiedStateLimit int64 = 100_000

	// ShortestPathI2QualifiedFrontierLimit is the immutable per-depth frontier
	// ceiling preregistered by the SP-I2 production-form protocol and policy seam.
	ShortestPathI2QualifiedFrontierLimit int64 = 100_000

	// ShortestPathSelectorStaticV6 identifies the evidence-gated production
	// selector for the qualified inbound, typed, single-kind canonical witness
	// envelope. The automatic selector remains sp-static-v5-contained until a
	// complete production evidence manifest activates this version.
	ShortestPathSelectorStaticV6 = "sp-static-v6"

	// ShortestPathSelectorStaticV7Contained extends contained S3/S4 selection
	// to syntax-open SP ranges using the existing effective depth-15 policy.
	ShortestPathSelectorStaticV7Contained = "sp-static-v7-contained"

	// ShortestPathSelectorStaticV8HiddenFanIn identifies the exact-bucket,
	// evidence-gated distance canary for asymmetric physical topology.
	ShortestPathSelectorStaticV8HiddenFanIn = "sp-static-v8-hidden-fanin"

	// ShortestPathSelectorStaticV9HiddenFanInTail is the default-off V2
	// selector identity. Production activation requires a V2 manifest.
	ShortestPathSelectorStaticV9HiddenFanInTail = "sp-static-v9-hidden-fanin-tail"

	// ShortestPathExecutorIncumbentWorkspace selects the existing workspace-table executor.
	ShortestPathExecutorIncumbentWorkspace ShortestPathExecutor = "SP-S0"

	// ShortestPathExecutorS1ArrayBFS selects breadth-first search with path state held in arrays.
	ShortestPathExecutorS1ArrayBFS ShortestPathExecutor = "SP-S1"

	// ShortestPathExecutorS2TraceRelation selects breadth-first search backed by a trace relation.
	ShortestPathExecutorS2TraceRelation ShortestPathExecutor = "SP-S2"

	// ShortestPathExecutorS3Unidirectional selects the unidirectional scalar-distance executor.
	ShortestPathExecutorS3Unidirectional ShortestPathExecutor = "SP-S3-U-D"

	// ShortestPathExecutorS3EdgeM0 selects unidirectional edge-trail search with deferred path materialization.
	ShortestPathExecutorS3EdgeM0 ShortestPathExecutor = "SP-S3-U-E+MAT-M0"

	// ShortestPathExecutorS0Direct selects the direct preflight executor with workspace fallback.
	ShortestPathExecutorS0Direct ShortestPathExecutor = "SP-S0-DIRECT"

	// ShortestPathExecutorS4CanonicalDistance selects canonical compact search for distance-only observations.
	ShortestPathExecutorS4CanonicalDistance ShortestPathExecutor = "SP-S4-C-D"

	// ShortestPathExecutorS4CanonicalWitness selects canonical compact search with witness materialization.
	ShortestPathExecutorS4CanonicalWitness ShortestPathExecutor = "SP-S4-C-WE+MAT-M0"

	// ShortestPathExecutorASPA1DAG selects all-shortest-path enumeration from a predecessor DAG.
	ShortestPathExecutorASPA1DAG ShortestPathExecutor = "ASP-A1-DAG"

	// ShortestPathExecutorASPN1NegativeExhaustion performs a bounded reverse
	// reachability preflight for no-path results and otherwise delegates to A1.
	// It is deliberately a distinct, default-off executor identity.
	ShortestPathExecutorASPN1NegativeExhaustion ShortestPathExecutor = "ASP-N1-NEGATIVE-EXHAUSTION"

	// ShortestPathExecutorI1CanonicalDistance selects an inline recursive SQL
	// distance search. The distinct identity prevents evidence collected at an
	// inline statement boundary from being attributed to a helper function.
	ShortestPathExecutorI1CanonicalDistance ShortestPathExecutor = "SP-I1-C-D"

	// ShortestPathExecutorI2GuardedDistance selects reverse-physical inline
	// distance discovery with exact compact S4 fallback.
	ShortestPathExecutorI2GuardedDistance ShortestPathExecutor = "SP-I2-C-D"

	// ShortestPathExecutorI2GuardedDistanceV2 selects the E1 V2 statement with
	// a single materialized admission decision and exact compact-S4 fallback.
	ShortestPathExecutorI2GuardedDistanceV2 ShortestPathExecutor = "SP-I2-C-D-V2"

	// Development identities are non-promotional and remain distinguishable in
	// diagnostic artifacts. Only E1 is emitted by the switch-free V2 builder.
	ShortestPathExecutorI2GuardedDistanceV2E0   ShortestPathExecutor = "SP-I2-C-D-V2-E0"
	ShortestPathExecutorI2GuardedDistanceV2E1   ShortestPathExecutor = "SP-I2-C-D-V2-E1"
	ShortestPathExecutorI2GuardedDistanceV2E1D  ShortestPathExecutor = "SP-I2-C-D-V2-E1D"
	ShortestPathExecutorI2GuardedDistanceV2E1P  ShortestPathExecutor = "SP-I2-C-D-V2-E1P"
	ShortestPathExecutorI2GuardedDistanceV2E1DP ShortestPathExecutor = "SP-I2-C-D-V2-E1DP"

	// ShortestPathExecutorI1CanonicalWitness selects inline recursive SQL with
	// ordered edge-ID witness state and late M0 path materialization.
	ShortestPathExecutorI1CanonicalWitness ShortestPathExecutor = "SP-I1-U-E+MAT-M0"

	// ShortestPathExecutorI1CanonicalPredecessorWitness selects guarded inline
	// minimum-distance/predecessor discovery, one deterministic witness, and an
	// exact compact S4 fallback. It is intentionally distinct from the legacy
	// unguarded relationship-trail I1 identity above.
	ShortestPathExecutorI1CanonicalPredecessorWitness ShortestPathExecutor = "SP-I1-C-WE+MAT-M0"

	// ShortestPathExecutorASPI1DAG selects inline predecessor-DAG discovery and
	// late M0 materialization for all shortest paths.
	ShortestPathExecutorASPI1DAG ShortestPathExecutor = "ASP-I1-U-DAG+MAT-M0"

	// ShortestPathExecutorB1AlternatingNodeDistance reserves compact bidirectional
	// distance search with strict node-at-a-time alternation.
	ShortestPathExecutorB1AlternatingNodeDistance ShortestPathExecutor = "SP-B1-C-ALT-NODE-D"

	// ShortestPathExecutorB1AlternatingNodeWitness reserves compact bidirectional
	// witness search with strict node-at-a-time alternation and deferred materialization.
	ShortestPathExecutorB1AlternatingNodeWitness ShortestPathExecutor = "SP-B1-C-ALT-NODE-WE+MAT-M0"

	// ShortestPathExecutorB2SmallerCurrentLevelDistance reserves compact bidirectional
	// distance search that expands the smaller current level.
	ShortestPathExecutorB2SmallerCurrentLevelDistance ShortestPathExecutor = "SP-B2-C-MIN-LEVEL-D"

	// ShortestPathExecutorB2SmallerCurrentLevelWitness reserves compact bidirectional
	// witness search that expands the smaller current level and defers materialization.
	ShortestPathExecutorB2SmallerCurrentLevelWitness ShortestPathExecutor = "SP-B2-C-MIN-LEVEL-WE+MAT-M0"

	// ShortestPathExecutorASPB1AlternatingNodeDAG reserves all-shortest-path DAG
	// enumeration with strict node-at-a-time alternation.
	ShortestPathExecutorASPB1AlternatingNodeDAG ShortestPathExecutor = "ASP-B1-DAG-ALT-NODE"

	// ShortestPathExecutorASPB2SmallerCurrentLevelDAG reserves all-shortest-path DAG
	// enumeration that expands the smaller current level.
	ShortestPathExecutorASPB2SmallerCurrentLevelDAG ShortestPathExecutor = "ASP-B2-DAG-MIN-LEVEL"
)
View Source 
const (
	// ShortestPathFallbackAllShortestPaths records an all-shortest-path query lacking singleton endpoints required by specialized execution.
	ShortestPathFallbackAllShortestPaths = "all_shortest_paths"

	// ShortestPathFallbackCorrelatedEndpoints rejects endpoint sources not proven uncorrelated, such as UNWIND or later query parts.
	ShortestPathFallbackCorrelatedEndpoints = "correlated_endpoints"

	// ShortestPathFallbackMultipleEndpointPairs rejects specialized execution when additional row sources prevent proving one endpoint pair.
	ShortestPathFallbackMultipleEndpointPairs = "multiple_endpoint_pairs"

	// ShortestPathFallbackNonSingletonID rejects an endpoint whose ID is not statically singleton.
	ShortestPathFallbackNonSingletonID = "non_singleton_id"

	// ShortestPathFallbackMultipleIDEqualities rejects an endpoint constrained by competing ID equalities.
	ShortestPathFallbackMultipleIDEqualities = "multiple_id_equalities"

	// ShortestPathFallbackPathPredicate rejects a predicate that observes the materialized path.
	ShortestPathFallbackPathPredicate = "path_predicate"

	// ShortestPathFallbackRelationshipPredicate rejects a predicate on the traversed relationship.
	ShortestPathFallbackRelationshipPredicate = "relationship_predicate"

	// ShortestPathFallbackRelationshipVariable rejects an observed relationship binding.
	ShortestPathFallbackRelationshipVariable = "relationship_variable"

	// ShortestPathFallbackDirectionless rejects a directionless shortest-path expansion.
	ShortestPathFallbackDirectionless = "directionless"

	// ShortestPathFallbackOptionalMatch rejects shortest-path work under OPTIONAL MATCH semantics.
	ShortestPathFallbackOptionalMatch = "optional_match"

	// ShortestPathFallbackUnsupportedDepth rejects a depth range unsupported by the candidate executor.
	ShortestPathFallbackUnsupportedDepth = "unsupported_depth"

	// ShortestPathFallbackMutation rejects specialized execution for a statement containing updates.
	ShortestPathFallbackMutation = "mutation"

	// ShortestPathFallbackMultiplePathCalls rejects statements containing more than one shortest-path pattern.
	ShortestPathFallbackMultiplePathCalls = "multiple_path_calls"

	// ShortestPathFallbackDeepInboundUnqualified rejects an unqualified deep inbound traversal.
	ShortestPathFallbackDeepInboundUnqualified = "deep_inbound_unqualified"

	// ShortestPathFallbackNonSingleKindPathState rejects compact path state without one relationship kind.
	ShortestPathFallbackNonSingleKindPathState = "non_single_kind_path_state_unqualified"

	// ShortestPathFallbackTournamentUnqualified records that no experimental candidate won qualification.
	ShortestPathFallbackTournamentUnqualified = "tournament_unqualified"
)
View Source 
const (
	// ExpansionSearchPolicyEndpointGuardV1 identifies the shipped endpoint and
	// reverse-state sentinel policy. It is distinct from topology orientation,
	// which requires root, suffix, and directional-degree probes.
	ExpansionSearchPolicyEndpointGuardV1 ExpansionSearchPolicy = "endpoint-state-guard-v1"

	// ExpansionSearchPolicyOrientationProbeV1 selects an ordinary-expansion
	// orientation from bounded, same-statement topology probes.
	ExpansionSearchPolicyOrientationProbeV1 ExpansionSearchPolicy = "orientation-probe-v1"

	// ExpansionSearchPolicyOrientationProbeV2 selects an ordinary-expansion
	// orientation using depth-weighted forward work and the same bounded,
	// same-statement topology probes as v1.
	ExpansionSearchPolicyOrientationProbeV2 ExpansionSearchPolicy = "orientation-probe-v2"

	// ExpansionSearchPolicySuffixReverseGuardV1 identifies bounded fixed-suffix
	// reverse execution with exact stepwise-forward fallback. Unlike the
	// orientation policies, it performs no topology scoring or directional
	// degree probes.
	ExpansionSearchPolicySuffixReverseGuardV1 ExpansionSearchPolicy = "suffix-reverse-guard-v1"

	// ExpansionSearchPolicySuffixReverseRetryV1 identifies the probe-free,
	// reverse-only fixed-suffix candidate whose exact forward fallback executes
	// as a second statement in the same stable-snapshot transaction.
	ExpansionSearchPolicySuffixReverseRetryV1 ExpansionSearchPolicy = "suffix-reverse-retry-v1"

	// ExpansionSearchPolicyTopologyFixedSuffixV1 identifies the production
	// topology-selected fixed-suffix candidate. It is distinct from every
	// tool-only suffix guard, retry, and component identity.
	ExpansionSearchPolicyTopologyFixedSuffixV1 ExpansionSearchPolicy = "topology-fixed-suffix-v1"

	// ExpansionSearchPolicyTopologyFixedSuffixFirstUseV1 identifies the
	// separately qualified first-use topology selector. Its manifest and route
	// protocol are intentionally distinct from v1's cache-hit-only contract.
	ExpansionSearchPolicyTopologyFixedSuffixFirstUseV1 ExpansionSearchPolicy = "topology-fixed-suffix-first-use-v1"

	// ExpansionSearchSelectorFixedSuffixPathV1 identifies the tool-only static
	// selector for full-path fixed-suffix observations.
	ExpansionSearchSelectorFixedSuffixPathV1 = "fixed-suffix-path-static-v1"

	// ExpansionSearchSelectorSuffixRouteComponentV1 identifies the default-off
	// GraphBench component arm for one exact suffix-seeded reverse statement.
	// It is not a production selector, cache identity, or routing policy.
	ExpansionSearchSelectorSuffixRouteComponentV1 = "suffix-route-component-v1"

	// ExpansionSearchSuffixReverseGuardSuffixRowLimit caps complete fixed-suffix
	// payload rows before reverse execution is admitted.
	ExpansionSearchSuffixReverseGuardSuffixRowLimit int64 = 512

	// ExpansionSearchSuffixReverseGuardStateLimit caps complete reverse recursive
	// state before exact forward fallback is selected.
	ExpansionSearchSuffixReverseGuardStateLimit int64 = 512

	// ExpansionSearchSuffixReverseRetryOutputRowLimit caps candidate rows buffered
	// before the transaction-local retry boundary exposes any result.
	ExpansionSearchSuffixReverseRetryOutputRowLimit int64 = 4_096

	// ExpansionSearchSuffixReverseRetryOutputBytesLimit caps the encoded candidate
	// payload buffered by the PostgreSQL driver before exact forward retry.
	ExpansionSearchSuffixReverseRetryOutputBytesLimit int64 = 16 * 1024 * 1024

	// ExpansionSearchOrientationRootRowLimit caps complete forward-root evidence
	// for the initial fixed-suffix orientation tournament.
	ExpansionSearchOrientationRootRowLimit int64 = 512

	// ExpansionSearchOrientationReverseSeedRowLimit caps complete fixed-suffix
	// row evidence while preserving duplicate suffix paths.
	ExpansionSearchOrientationReverseSeedRowLimit int64 = 512

	// ExpansionSearchOrientationDirectionalDegreeRowLimit caps each typed
	// directional adjacency probe independently.
	ExpansionSearchOrientationDirectionalDegreeRowLimit int64 = 16_384

	// ExpansionSearchOrientationStateLimit caps admitted reverse recursive state.
	ExpansionSearchOrientationStateLimit int64 = 4_096

	// ExpansionSearchOrientationReverseScoreMultiplier is the reverse side of
	// orientation-probe-v1's strict 3/4 hysteresis comparison.
	ExpansionSearchOrientationReverseScoreMultiplier int64 = 4

	// ExpansionSearchOrientationForwardScoreMultiplier is the incumbent side
	// of orientation-probe-v1's strict 3/4 hysteresis comparison.
	ExpansionSearchOrientationForwardScoreMultiplier int64 = 3

	// ExpansionSearchOrientationV2ReverseScoreMultiplier is the reverse side
	// of orientation-probe-v2's strict 3/4 hysteresis comparison.
	ExpansionSearchOrientationV2ReverseScoreMultiplier int64 = 4

	// ExpansionSearchOrientationV2ForwardScoreMultiplier is the incumbent side
	// of orientation-probe-v2's strict 3/4 hysteresis comparison.
	ExpansionSearchOrientationV2ForwardScoreMultiplier int64 = 3

	// ExpansionSearchExecutionBoundaryInlineStatement identifies one emitted
	// expansion traversal arm in the translated statement.
	ExpansionSearchExecutionBoundaryInlineStatement = "inline_statement"

	// ExpansionSearchExecutionBoundaryGuardedDualArm identifies a
	// same-statement expansion policy with exact candidate and fallback arms.
	ExpansionSearchExecutionBoundaryGuardedDualArm = "guarded_dual_arm"

	// ExpansionSearchExecutionBoundaryTransactionRetry identifies a reverse-only
	// statement plus exact incumbent retry inside one stable-snapshot transaction.
	ExpansionSearchExecutionBoundaryTransactionRetry = "transaction_retry"
)
View Source 
const (
	// ExpansionSearchFallbackNoFixedSuffix rejects a strategy that requires a fixed suffix when none exists.
	ExpansionSearchFallbackNoFixedSuffix = "no_fixed_suffix"

	// ExpansionSearchFallbackSuffixTooShort rejects a fixed suffix below the strategy's minimum length.
	ExpansionSearchFallbackSuffixTooShort = "suffix_too_short"

	// ExpansionSearchFallbackOptionalMatch rejects a rewrite that would alter OPTIONAL MATCH behavior.
	ExpansionSearchFallbackOptionalMatch = "optional_match"

	// ExpansionSearchFallbackShortestPath rejects ordinary-expansion strategies for shortestPath patterns.
	ExpansionSearchFallbackShortestPath = "shortest_path"

	// ExpansionSearchFallbackAllShortestPaths rejects ordinary-expansion strategies for allShortestPaths patterns.
	ExpansionSearchFallbackAllShortestPaths = "all_shortest_paths"

	// ExpansionSearchFallbackDirectionlessExpansion rejects a directionless variable expansion.
	ExpansionSearchFallbackDirectionlessExpansion = "directionless_expansion"

	// ExpansionSearchFallbackDirectionlessSuffix rejects a directionless edge in the fixed suffix.
	ExpansionSearchFallbackDirectionlessSuffix = "directionless_suffix"

	// ExpansionSearchFallbackUnboundedDepth rejects an expansion without a finite maximum depth.
	ExpansionSearchFallbackUnboundedDepth = "unbounded_depth"

	// ExpansionSearchFallbackUnsupportedDepth rejects a depth range the candidate cannot preserve.
	ExpansionSearchFallbackUnsupportedDepth = "unsupported_depth"

	// ExpansionSearchFallbackMultipleVariableExpansions rejects regions containing more than one variable expansion.
	ExpansionSearchFallbackMultipleVariableExpansions = "multiple_variable_expansions"

	// ExpansionSearchFallbackCorrelatedSuffix rejects a fixed suffix that reuses an outer binding.
	ExpansionSearchFallbackCorrelatedSuffix = "correlated_suffix"

	// ExpansionSearchFallbackCrossRegionPredicate rejects predicates spanning the variable and fixed regions.
	ExpansionSearchFallbackCrossRegionPredicate = "cross_region_predicate"

	// ExpansionSearchFallbackPathDependentPredicate rejects predicates that depend on accumulated path state.
	ExpansionSearchFallbackPathDependentPredicate = "path_dependent_predicate"

	// ExpansionSearchFallbackRelationshipVariable rejects an observed relationship binding in the variable expansion or fixed suffix.
	ExpansionSearchFallbackRelationshipVariable = "relationship_variable"

	// ExpansionSearchFallbackRelationshipPredicate rejects relationship predicates in the variable expansion or fixed suffix.
	ExpansionSearchFallbackRelationshipPredicate = "relationship_predicate"

	// ExpansionSearchFallbackLimitPushdownConflict rejects a rewrite that conflicts with an existing limit pushdown.
	ExpansionSearchFallbackLimitPushdownConflict = "limit_pushdown_conflict"

	// ExpansionSearchFallbackUnsupportedObservation rejects downstream uses the candidate cannot reconstruct.
	ExpansionSearchFallbackUnsupportedObservation = "unsupported_observation"

	// ExpansionSearchFallbackMutation rejects specialized search for a statement containing updates.
	ExpansionSearchFallbackMutation = "mutation"

	// ExpansionSearchFallbackNonDeterministicPredicate rejects a seed predicate that cannot be safely reordered.
	ExpansionSearchFallbackNonDeterministicPredicate = "non_deterministic_predicate"

	// ExpansionSearchFallbackUnboundRoot rejects a strategy that requires a previously bound expansion root.
	ExpansionSearchFallbackUnboundRoot = "unbound_root"

	// ExpansionSearchFallbackTournamentUnqualified records that no specialized strategy passed qualification.
	ExpansionSearchFallbackTournamentUnqualified = "tournament_unqualified"

	// ExpansionSearchFallbackNoFixedPrefix rejects a strategy that requires a fixed prefix when none exists.
	ExpansionSearchFallbackNoFixedPrefix = "no_fixed_prefix"

	// ExpansionSearchFallbackExpansionNotTerminal rejects endpoint seeding when the expansion is not terminal.
	ExpansionSearchFallbackExpansionNotTerminal = "expansion_not_terminal"

	// ExpansionSearchFallbackPrefixTooLong rejects a prefix that is not exactly one fixed hop.
	ExpansionSearchFallbackPrefixTooLong = "prefix_too_long"

	// ExpansionSearchFallbackDirectionlessPrefix rejects a directionless edge in the fixed prefix.
	ExpansionSearchFallbackDirectionlessPrefix = "directionless_prefix"

	// ExpansionSearchFallbackTerminalNotSelective rejects endpoint seeding without a selective terminal predicate.
	ExpansionSearchFallbackTerminalNotSelective = "terminal_not_selective"

	// ExpansionSearchFallbackCorrelatedTerminal rejects a pre-bound terminal or a terminal predicate that depends on another binding.
	ExpansionSearchFallbackCorrelatedTerminal = "correlated_terminal"

	// ExpansionSearchFallbackZeroDepth rejects a rewrite that cannot preserve zero-length paths.
	ExpansionSearchFallbackZeroDepth = "zero_depth"
)
View Source 
const (
	// EndpointResolutionSingletonLimit reserves the stable protocol value used to recognize endpoint resolution singleton limit across artifacts and executions.
	EndpointResolutionSingletonLimit int64 = 1

	// EndpointResolutionSingletonSentinel reserves the stable protocol value used to recognize endpoint resolution singleton sentinel across artifacts and executions.
	EndpointResolutionSingletonSentinel int64 = 2

	// EndpointResolutionSmallSetLimit reserves the stable protocol value used to recognize endpoint resolution small set limit across artifacts and executions.
	EndpointResolutionSmallSetLimit int64 = 32

	// EndpointResolutionSmallSetSentinel reserves the stable protocol value used to recognize endpoint resolution small set sentinel across artifacts and executions.
	EndpointResolutionSmallSetSentinel int64 = 33
)

Endpoint-resolution limits are immutable analysis metadata for the first bounded-resolution envelope. Each runtime limit has an explicit cap+1 sentinel; this slice records the contract without changing execution.

View Source 
const (
	// EndpointResolutionFallbackPlannedOnly reserves the stable protocol value used to recognize endpoint resolution fallback planned only across artifacts and executions.
	EndpointResolutionFallbackPlannedOnly = "planned_only"

	// EndpointResolutionFallbackMutation reserves the stable protocol value used to recognize endpoint resolution fallback mutation across artifacts and executions.
	EndpointResolutionFallbackMutation = "mutation"

	// EndpointResolutionFallbackOptionalMatch reserves the stable protocol value used to recognize endpoint resolution fallback optional match across artifacts and executions.
	EndpointResolutionFallbackOptionalMatch = "optional_match"

	// EndpointResolutionFallbackCorrelatedPair reserves the stable protocol value used to recognize endpoint resolution fallback correlated pair across artifacts and executions.
	EndpointResolutionFallbackCorrelatedPair = "correlated_pair"

	// EndpointResolutionFallbackUnsupported reserves the stable protocol value used to recognize endpoint resolution fallback unsupported across artifacts and executions.
	EndpointResolutionFallbackUnsupported = "unsupported_endpoint_class"

	// EndpointResolutionFallbackSmallSetOverflow reserves the stable protocol value used to recognize endpoint resolution fallback small set overflow across artifacts and executions.
	EndpointResolutionFallbackSmallSetOverflow = "explicit_small_set_overflow"
)
View Source 
const (
	// TraversalPredicateFallbackPlannedOnly reserves the stable protocol value used to recognize traversal predicate fallback planned only across artifacts and executions.
	TraversalPredicateFallbackPlannedOnly = "planned_only"

	// TraversalPredicateFallbackMutation reserves the stable protocol value used to recognize traversal predicate fallback mutation across artifacts and executions.
	TraversalPredicateFallbackMutation = "mutation"

	// TraversalPredicateFallbackOptional reserves the stable protocol value used to recognize traversal predicate fallback optional across artifacts and executions.
	TraversalPredicateFallbackOptional = "optional_match"

	// TraversalPredicateFallbackCorrelation reserves the stable protocol value used to recognize traversal predicate fallback correlation across artifacts and executions.
	TraversalPredicateFallbackCorrelation = "correlated_predicate"

	// TraversalPredicateFallbackWholePath reserves the stable protocol value used to recognize traversal predicate fallback whole path across artifacts and executions.
	TraversalPredicateFallbackWholePath = "whole_path"

	// TraversalPredicateFallbackUnsupported reserves the stable protocol value used to recognize traversal predicate fallback unsupported across artifacts and executions.
	TraversalPredicateFallbackUnsupported = "unsupported_predicate"
)

Variables

This section is empty.

Functions

func AddFromClauseBindings 

func AddFromClauseBindings(localScope *pgsql.IdentifierSet, fromClauses []pgsql.FromClause)

func AddFromExpressionBinding 

func AddFromExpressionBinding(localScope *pgsql.IdentifierSet, expression pgsql.Expression)

func ExactPatternRangeDepth added in v0.7.0 

func ExactPatternRangeDepth(patternRange *cypher.PatternRange) int64

ExactPatternRangeDepth evaluates planner state needed for exact pattern range depth.

func ExpressionReferencesOnlyLocalIdentifiers 

func ExpressionReferencesOnlyLocalIdentifiers(expression pgsql.Expression, localScope *pgsql.IdentifierSet) bool

ExpressionReferencesOnlyLocalIdentifiers returns true only when every binding reference found in the expression is a member of localScope.

func FlattenConjunction 

func FlattenConjunction(expr pgsql.Expression) []pgsql.Expression

FlattenConjunction collects the leaf operands of a left-recursive AND chain.

func FromExpressionReferencesOnlyLocalIdentifiers 

func FromExpressionReferencesOnlyLocalIdentifiers(expression pgsql.Expression, localScopes ...*pgsql.IdentifierSet) bool

func IndexPatternPredicateTargets 

func IndexPatternPredicateTargets(query *cypher.RegularQuery) map[*cypher.PatternPredicate]PatternTarget

IndexPatternPredicateTargets evaluates planner state needed for index pattern predicate targets.

func IndexPatternTargets 

func IndexPatternTargets(query *cypher.RegularQuery) map[*cypher.PatternPart]PatternTarget

IndexPatternTargets evaluates planner state needed for index pattern targets.

func IsBidirectionalSearchAnchor 

func IsBidirectionalSearchAnchor(selectivity int) bool

func IsLocalToScope 

func IsLocalToScope(expression pgsql.Expression, localScope *pgsql.IdentifierSet) bool

func MeasureSelectivity 

func MeasureSelectivity(bindings BindingLookup, expression pgsql.Expression) (int, error)

func PartitionConstraintByLocality 

func PartitionConstraintByLocality(expression pgsql.Expression, localScope *pgsql.IdentifierSet) (pgsql.Expression, pgsql.Expression)

PartitionConstraintByLocality splits a conjunction (A AND B AND ...) into two expressions: one whose every binding reference is contained in localScope (safe for JOIN ON), and one that references outside identifiers (must stay in WHERE).

Only top-level AND operands are split. If an expression is not a BinaryExpression with OperatorAnd, the whole expression is tested as a unit.

func QueryReferencesOnlyLocalIdentifiers 

func QueryReferencesOnlyLocalIdentifiers(query pgsql.Query, localScope *pgsql.IdentifierSet) bool

func SelectReferencesOnlyLocalIdentifiers 

func SelectReferencesOnlyLocalIdentifiers(selectBody pgsql.Select, localScope *pgsql.IdentifierSet) bool

func SubqueryReferencesOnlyLocalIdentifiers 

func SubqueryReferencesOnlyLocalIdentifiers(subquery pgsql.Subquery, localScope *pgsql.IdentifierSet) bool

Types

type AggregateTraversalCountDecision 

type AggregateTraversalCountDecision struct {
	// QueryPartIndex supplies the query part index input to the AggregateTraversalCountDecision contract.
	QueryPartIndex int `json:"query_part_index"`
	// SourceSymbol supplies the source symbol input to the AggregateTraversalCountDecision contract.
	SourceSymbol string `json:"source_symbol"`
	// TerminalSymbol supplies the terminal symbol input to the AggregateTraversalCountDecision contract.
	TerminalSymbol string `json:"terminal_symbol"`
	// CountAlias supplies the count alias input to the AggregateTraversalCountDecision contract.
	CountAlias string `json:"count_alias"`
	// Limit supplies the limit input to the AggregateTraversalCountDecision contract.
	Limit int64 `json:"limit,omitempty"`
	// Target supplies the target input to the AggregateTraversalCountDecision contract.
	Target TraversalStepTarget `json:"target"`
}

AggregateTraversalCountDecision records the planner choice made for aggregate traversal count.

type AggregateTraversalCountShape 

type AggregateTraversalCountShape struct {
	// QueryPartIndex supplies the query part index input to the AggregateTraversalCountShape contract.
	QueryPartIndex int
	// SourceSymbol supplies the source symbol input to the AggregateTraversalCountShape contract.
	SourceSymbol string
	// TerminalSymbol supplies the terminal symbol input to the AggregateTraversalCountShape contract.
	TerminalSymbol string
	// CountAlias supplies the count alias input to the AggregateTraversalCountShape contract.
	CountAlias string
	// ReturnSourceAlias supplies the return source alias input to the AggregateTraversalCountShape contract.
	ReturnSourceAlias string
	// ReturnCountAlias supplies the return count alias input to the AggregateTraversalCountShape contract.
	ReturnCountAlias string
	// ReturnCount records the number of return count.
	ReturnCount bool
	// Limit supplies the limit input to the AggregateTraversalCountShape contract.
	Limit int64
	// SourceMatch supplies the source match input to the AggregateTraversalCountShape contract.
	SourceMatch *cypher.Match
	// TerminalMatch supplies the terminal match input to the AggregateTraversalCountShape contract.
	TerminalMatch *cypher.Match
	// SourceKinds supplies the source kinds input to the AggregateTraversalCountShape contract.
	SourceKinds graph.Kinds
	// TerminalKinds supplies the terminal kinds input to the AggregateTraversalCountShape contract.
	TerminalKinds graph.Kinds
	// RelationshipKinds supplies the relationship kinds input to the AggregateTraversalCountShape contract.
	RelationshipKinds graph.Kinds
	// Direction selects the traversal orientation covered by the contract.
	Direction graph.Direction
	// MinDepth supplies the min depth input to the AggregateTraversalCountShape contract.
	MinDepth int64
	// MaxDepth supplies the max depth input to the AggregateTraversalCountShape contract.
	MaxDepth int64
	// Target supplies the target input to the AggregateTraversalCountShape contract.
	Target TraversalStepTarget
}

AggregateTraversalCountShape groups planner state that must remain consistent while analyzing aggregate traversal count shape.

func AggregateTraversalCountShapeForQuery 

func AggregateTraversalCountShapeForQuery(query *cypher.RegularQuery) (AggregateTraversalCountShape, bool)

AggregateTraversalCountShapeForQuery constructs the SQL model used for aggregate traversal count shape for query.

type Analysis 

type Analysis struct {
	QueryParts []QueryPart
}

func Analyze 

func Analyze(query *cypher.RegularQuery) Analysis

func (Analysis) Diagnostics 

func (s Analysis) Diagnostics() []string

func (Analysis) String 

func (s Analysis) String() string

type Barrier 

type Barrier struct {
	QueryPartIndex int
	ClauseIndex    int
	Kind           BarrierKind
	Dependencies   []string
}

type BarrierKind 

type BarrierKind string
const (
	BarrierKindReturn        BarrierKind = "return"
	BarrierKindWith          BarrierKind = "with"
	BarrierKindUnwind        BarrierKind = "unwind"
	BarrierKindOptionalMatch BarrierKind = "optional_match"
	BarrierKindUpdate        BarrierKind = "update"
)

type Binding 

type Binding struct {
	Symbol       string
	Kind         BindingKind
	ClauseIndex  int
	PatternIndex int
}

type BindingKind 

type BindingKind string
const (
	BindingKindNode         BindingKind = "node"
	BindingKindRelationship BindingKind = "relationship"
	BindingKindPath         BindingKind = "path"
)

type BindingLookup 

type BindingLookup interface {
	LookupDataType(identifier pgsql.Identifier) (pgsql.DataType, bool)
}

type ConservativePatternReorderingRule 

type ConservativePatternReorderingRule struct{}

ConservativePatternReorderingRule reorders reading clauses within a dependency-safe region so that more selective anchors are scheduled earlier, driving traversals from the endpoints expected to prune the search soonest. It reorders whole clauses relative to one another without mutating the internals of any pattern; a clause is only moved when its dependencies remain satisfied by the clauses that precede it in the new order.

func (ConservativePatternReorderingRule) Apply 

func (s ConservativePatternReorderingRule) Apply(plan *Plan) (bool, error)

func (ConservativePatternReorderingRule) Name 

func (s ConservativePatternReorderingRule) Name() string

type CountStoreFastPathDecision 

type CountStoreFastPathDecision struct {
	// QueryPartIndex supplies the query part index input to the CountStoreFastPathDecision contract.
	QueryPartIndex int `json:"query_part_index"`
	// ClauseIndex supplies the clause index input to the CountStoreFastPathDecision contract.
	ClauseIndex int `json:"clause_index"`
	// PatternIndex supplies the pattern index input to the CountStoreFastPathDecision contract.
	PatternIndex int `json:"pattern_index"`
	// BindingSymbol supplies the binding symbol input to the CountStoreFastPathDecision contract.
	BindingSymbol string `json:"binding_symbol,omitempty"`
	// Target supplies the target input to the CountStoreFastPathDecision contract.
	Target CountStoreFastPathTarget `json:"target"`
	// KindSymbols supplies the kind symbols input to the CountStoreFastPathDecision contract.
	KindSymbols []string `json:"kind_symbols,omitempty"`
}

CountStoreFastPathDecision records the planner choice made for count store fast path.

type CountStoreFastPathTarget 

type CountStoreFastPathTarget string
const (
	// CountStoreFastPathNode reads a node count directly from graph statistics.
	CountStoreFastPathNode CountStoreFastPathTarget = "node"

	// CountStoreFastPathEdge reads a relationship count directly from graph statistics.
	CountStoreFastPathEdge CountStoreFastPathTarget = "edge"
)

type EndpointResolutionCaps added in v1.0.0 

type EndpointResolutionCaps struct {
	// SingletonLimit supplies the singleton limit input to the EndpointResolutionCaps contract.
	SingletonLimit int64 `json:"singleton_limit"`
	// SingletonSentinel supplies the singleton sentinel input to the EndpointResolutionCaps contract.
	SingletonSentinel int64 `json:"singleton_sentinel"`
	// SmallSetLimit supplies the small set limit input to the EndpointResolutionCaps contract.
	SmallSetLimit int64 `json:"small_set_limit"`
	// SmallSetSentinel supplies the small set sentinel input to the EndpointResolutionCaps contract.
	SmallSetSentinel int64 `json:"small_set_sentinel"`
}

EndpointResolutionCaps serializes both admitted cardinalities and their overflow sentinels so future SQL cannot silently reinterpret the contract.

type EndpointResolutionClass added in v1.0.0 

type EndpointResolutionClass string

EndpointResolutionClass identifies how one traversal endpoint, or a correlated endpoint pair, could be resolved before traversal. 

const (
	// EndpointResolutionClassIDEquality reserves the stable protocol value used to recognize endpoint resolution class id equality across artifacts and executions.
	EndpointResolutionClassIDEquality EndpointResolutionClass = "id_equality"

	// EndpointResolutionClassUniquePropertyEquality reserves the stable protocol value used to recognize endpoint resolution class unique property equality across artifacts and executions.
	EndpointResolutionClassUniquePropertyEquality EndpointResolutionClass = "unique_property_equality"

	// EndpointResolutionClassNonUniquePropertyEquality reserves the stable protocol value used to recognize endpoint resolution class non unique property equality across artifacts and executions.
	EndpointResolutionClassNonUniquePropertyEquality EndpointResolutionClass = "nonunique_property_equality"

	// EndpointResolutionClassExplicitSmallSet reserves the stable protocol value used to recognize endpoint resolution class explicit small set across artifacts and executions.
	EndpointResolutionClassExplicitSmallSet EndpointResolutionClass = "explicit_small_set"

	// EndpointResolutionClassCorrelatedPair reserves the stable protocol value used to recognize endpoint resolution class correlated pair across artifacts and executions.
	EndpointResolutionClassCorrelatedPair EndpointResolutionClass = "correlated_pair"

	// EndpointResolutionClassUnsupported reserves the stable protocol value used to recognize endpoint resolution class unsupported across artifacts and executions.
	EndpointResolutionClassUnsupported EndpointResolutionClass = "unsupported"
)

type EndpointResolutionDecision added in v1.0.0 

type EndpointResolutionDecision struct {
	// Target supplies the target input to the EndpointResolutionDecision contract.
	Target TraversalStepTarget `json:"target"`
	// Family supplies the family input to the EndpointResolutionDecision contract.
	Family string `json:"family"`
	// Root supplies the root input to the EndpointResolutionDecision contract.
	Root EndpointResolutionInput `json:"root"`
	// Terminal supplies the terminal input to the EndpointResolutionDecision contract.
	Terminal EndpointResolutionInput `json:"terminal"`
	// PairClass supplies the pair class input to the EndpointResolutionDecision contract.
	PairClass EndpointResolutionClass `json:"pair_class,omitempty"`
	// PlannedClasses supplies the planned classes input to the EndpointResolutionDecision contract.
	PlannedClasses []EndpointResolutionClass `json:"planned_classes"`
	// Caps binds each guarded resource dimension to its enforced limit.
	Caps EndpointResolutionCaps `json:"caps"`
	// PlannedCandidates supplies the planned candidates input to the EndpointResolutionDecision contract.
	PlannedCandidates []EndpointResolutionPlan `json:"planned_candidates"`
	// CandidatePlan supplies the candidate plan input to the EndpointResolutionDecision contract.
	CandidatePlan EndpointResolutionPlan `json:"candidate_plan"`
	// SelectedPlan supplies the selected plan input to the EndpointResolutionDecision contract.
	SelectedPlan EndpointResolutionPlan `json:"selected_plan"`
	// FallbackPlan supplies the fallback plan input to the EndpointResolutionDecision contract.
	FallbackPlan EndpointResolutionPlan `json:"fallback_plan"`
	// EligibilityFacts supplies the eligibility facts input to the EndpointResolutionDecision contract.
	EligibilityFacts []EndpointResolutionEligibilityFact `json:"eligibility_facts"`
	// StructurallyEligible indicates whether structurally eligible applies.
	StructurallyEligible bool `json:"structurally_eligible"`
	// StaticallyEligible indicates whether statically eligible applies.
	StaticallyEligible bool `json:"statically_eligible"`
	// SelectionMode identifies the selection mode.
	SelectionMode string `json:"selection_mode"`
	// SelectorVersion identifies the schema version for selector version.
	SelectorVersion string `json:"selector_version"`
	// FallbackReason supplies the fallback reason input to the EndpointResolutionDecision contract.
	FallbackReason string `json:"fallback_reason"`
}

EndpointResolutionDecision is analysis-only metadata for one SP/ASP traversal. The exact existing resolver remains selected in this milestone.

type EndpointResolutionEligibilityFact added in v1.0.0 

type EndpointResolutionEligibilityFact struct {
	// Name identifies the name.
	Name string `json:"name"`
	// Eligible indicates whether eligible applies.
	Eligible bool `json:"eligible"`
}

EndpointResolutionEligibilityFact records one conservative qualification check for bounded endpoint materialization.

type EndpointResolutionInput added in v1.0.0 

type EndpointResolutionInput struct {
	// Symbol supplies the symbol input to the EndpointResolutionInput contract.
	Symbol string `json:"symbol"`
	// Class supplies the class input to the EndpointResolutionInput contract.
	Class EndpointResolutionClass `json:"class"`
	// Property supplies the property input to the EndpointResolutionInput contract.
	Property string `json:"property,omitempty"`
	// StaticValueCount records the number of static value count.
	StaticValueCount int `json:"static_value_count,omitempty"`
	// ParameterizedSet indicates whether parameterized set applies.
	ParameterizedSet bool `json:"parameterized_set,omitempty"`
	// Limit supplies the limit input to the EndpointResolutionInput contract.
	Limit int64 `json:"limit,omitempty"`
	// Sentinel supplies the sentinel input to the EndpointResolutionInput contract.
	Sentinel int64 `json:"sentinel,omitempty"`
}

EndpointResolutionInput records one endpoint's statically recognizable resolution shape. Cardinality remains runtime evidence.

type EndpointResolutionPlan added in v1.0.0 

type EndpointResolutionPlan string

EndpointResolutionPlan identifies the exact incumbent and the planned-only bounded resolver independently of any shortest-path executor. 

const (
	// EndpointResolutionPlanIncumbent reserves the stable protocol value used to recognize endpoint resolution plan incumbent across artifacts and executions.
	EndpointResolutionPlanIncumbent EndpointResolutionPlan = "ENDPOINT-RESOLUTION-INCUMBENT"

	// EndpointResolutionPlanBounded reserves the stable protocol value used to recognize endpoint resolution plan bounded across artifacts and executions.
	EndpointResolutionPlanBounded EndpointResolutionPlan = "ENDPOINT-RESOLUTION-BOUNDED"
)

type ExactRangeExpansionDecision added in v0.7.0 

type ExactRangeExpansionDecision struct {
	// Target supplies the target input to the ExactRangeExpansionDecision contract.
	Target TraversalStepTarget `json:"target"`
	// Depth supplies the depth input to the ExactRangeExpansionDecision contract.
	Depth int64 `json:"depth"`
}

ExactRangeExpansionDecision records the planner choice made for exact range expansion.

type ExpandIntoDecision 

type ExpandIntoDecision struct {
	// Target supplies the target input to the ExpandIntoDecision contract.
	Target TraversalStepTarget `json:"target"`
}

ExpandIntoDecision records the planner choice made for expand into.

type ExpansionSearchAdmission added in v1.0.0 

type ExpansionSearchAdmission struct {
	// StateLimit caps specialized search state before incumbent fallback.
	StateLimit int64 `json:"state_limit,omitempty"`
	// OutputRowLimit caps candidate rows buffered before publication.
	OutputRowLimit int64 `json:"output_row_limit,omitempty"`
	// OutputBytesLimit caps the encoded candidate payload buffered before publication.
	OutputBytesLimit int64 `json:"output_bytes_limit,omitempty"`
	// RequiresCompleteProbes requires every candidate input probe to remain at
	// or below its declared cap before specialized rows may be exposed.
	RequiresCompleteProbes bool `json:"requires_complete_probes,omitempty"`
	// FallbackStrategy names the exact incumbent used when admission fails.
	FallbackStrategy ExpansionSearchStrategy `json:"fallback_strategy,omitempty"`
}

ExpansionSearchAdmission records the exact gate and fallback for a specialized orientation arm.

type ExpansionSearchEligibilityFact added in v1.0.0 

type ExpansionSearchEligibilityFact struct {
	// Name identifies the qualification check.
	Name string `json:"name"`
	// Eligible reports whether the strategy passed the named check.
	Eligible bool `json:"eligible"`
}

ExpansionSearchEligibilityFact records one named qualification check for a search strategy.

type ExpansionSearchObservationMode added in v1.0.0 

type ExpansionSearchObservationMode string
const (
	// ExpansionSearchObservationEndpointIDs indicates that downstream clauses consume only endpoint IDs.
	ExpansionSearchObservationEndpointIDs ExpansionSearchObservationMode = "endpoint_ids"

	// ExpansionSearchObservationOrderedPathIDs indicates that downstream clauses consume ordered path IDs.
	ExpansionSearchObservationOrderedPathIDs ExpansionSearchObservationMode = "ordered_path_ids"

	// ExpansionSearchObservationFullPath indicates that downstream clauses consume hydrated path values.
	ExpansionSearchObservationFullPath ExpansionSearchObservationMode = "full_path"

	// ExpansionSearchObservationUnsupported indicates an observation pattern unsupported by specialized search.
	ExpansionSearchObservationUnsupported ExpansionSearchObservationMode = "unsupported"
)

type ExpansionSearchPolicy added in v1.0.0 

type ExpansionSearchPolicy string

ExpansionSearchPolicy identifies a runtime policy independently of the expansion arm that the policy may execute.

type ExpansionSearchProbeCaps added in v1.0.0 

type ExpansionSearchProbeCaps struct {
	// RootRowLimit caps forward-root evidence.
	RootRowLimit int64 `json:"root_row_limit,omitempty"`
	// ReverseSeedRowLimit caps terminal or fixed-suffix seed evidence.
	ReverseSeedRowLimit int64 `json:"reverse_seed_row_limit,omitempty"`
	// DirectionalDegreeRowLimit caps typed first-hop adjacency evidence.
	DirectionalDegreeRowLimit int64 `json:"directional_degree_row_limit,omitempty"`
	// SurvivalRowLimit caps optional one-level survival evidence.
	SurvivalRowLimit int64 `json:"survival_row_limit,omitempty"`
}

ExpansionSearchProbeCaps records the maximum complete evidence admitted by an orientation policy. SQL probes use cap+1 sentinels to detect overflow.

type ExpansionSearchStrategy added in v1.0.0 

type ExpansionSearchStrategy string
const (
	// ExpansionSearchStepwiseForward selects the incumbent left-to-right expansion plan.
	ExpansionSearchStepwiseForward ExpansionSearchStrategy = "EXPANSION-STEPWISE-FORWARD"

	// ExpansionSearchLateHydratedForward selects forward search with deferred entity hydration.
	ExpansionSearchLateHydratedForward ExpansionSearchStrategy = "EXPANSION-LATE-HYDRATED-FORWARD"

	// ExpansionSearchFactoredSuffixForward selects forward search with a factored fixed suffix.
	ExpansionSearchFactoredSuffixForward ExpansionSearchStrategy = "EXPANSION-FACTORED-SUFFIX-FORWARD"

	// ExpansionSearchSuffixSeededReverse selects reverse probing seeded from a selective fixed suffix.
	ExpansionSearchSuffixSeededReverse ExpansionSearchStrategy = "EXPANSION-SUFFIX-SEEDED-REVERSE"

	// ExpansionSearchEndpointSeededReverse selects reverse probing seeded from selective terminal endpoints.
	ExpansionSearchEndpointSeededReverse ExpansionSearchStrategy = "EXPANSION-ENDPOINT-SEEDED-REVERSE"

	// ExpansionSearchBackwardViabilityForward selects forward expansion gated by backward reachability.
	ExpansionSearchBackwardViabilityForward ExpansionSearchStrategy = "EXPANSION-BACKWARD-VIABILITY-FORWARD"
)

type ExpansionSearchStrategyDecision added in v1.0.0 

type ExpansionSearchStrategyDecision struct {
	// Target locates the variable-expansion step governed by this decision.
	Target TraversalStepTarget `json:"target"`
	// Family names the search-strategy family that produced the decision.
	Family string `json:"family"`
	// PlannedPolicy identifies the runtime policy intended for this candidate
	// family, whether or not translation currently emits it.
	PlannedPolicy ExpansionSearchPolicy `json:"planned_policy,omitempty"`
	// EmittedPolicy identifies the runtime policy actually present in emitted
	// SQL. It remains empty for a single forced arm or incumbent-only SQL.
	EmittedPolicy ExpansionSearchPolicy `json:"emitted_policy,omitempty"`
	// PlannedCandidates lists the strategies considered in preference order.
	PlannedCandidates []ExpansionSearchStrategy `json:"planned_candidates"`
	// EmittedCandidates lists the arms present in the translated statement.
	// Runtime telemetry, not this field, records which arm executed.
	EmittedCandidates []ExpansionSearchStrategy `json:"emitted_candidates,omitempty"`
	// ExecutionBoundary describes the SQL boundary that contains the emitted
	// expansion arm or guarded policy.
	ExecutionBoundary string `json:"execution_boundary,omitempty"`
	// ProbeCaps records bounded evidence inputs for the planned policy.
	ProbeCaps ExpansionSearchProbeCaps `json:"probe_caps"`
	// Admission supplies the admission input to the ExpansionSearchStrategyDecision contract.
	Admission ExpansionSearchAdmission `json:"admission"`
	// CandidateStrategy is the specialized strategy proposed by structural analysis.
	CandidateStrategy ExpansionSearchStrategy `json:"candidate_strategy,omitempty"`
	// SelectedStrategy is the strategy chosen after all qualification checks.
	SelectedStrategy ExpansionSearchStrategy `json:"selected_strategy"`
	// StructurallyEligible reports whether the traversal shape supports the candidate.
	StructurallyEligible bool `json:"structurally_eligible"`
	// StaticallyEligible reports whether known bounds and predicates support the candidate.
	StaticallyEligible bool `json:"statically_eligible"`
	// EligibilityFacts records each qualification check and its result.
	EligibilityFacts []ExpansionSearchEligibilityFact `json:"eligibility_facts"`
	// SuffixStartStep is the first traversal step in the fixed suffix.
	SuffixStartStep int `json:"suffix_start_step,omitempty"`
	// SuffixEndStep is the last traversal step in the fixed suffix.
	SuffixEndStep int `json:"suffix_end_step,omitempty"`
	// SuffixLength is the number of traversal steps in the fixed suffix.
	SuffixLength int `json:"suffix_length,omitempty"`
	// PrefixStartStep is the first traversal step in the fixed prefix.
	PrefixStartStep int `json:"prefix_start_step,omitempty"`
	// PrefixEndStep is the last traversal step in the fixed prefix.
	PrefixEndStep int `json:"prefix_end_step,omitempty"`
	// PrefixLength is the number of traversal steps in the fixed prefix.
	PrefixLength int `json:"prefix_length,omitempty"`
	// SeedPredicateClass describes the predicate used to bound reverse search seeds.
	SeedPredicateClass string `json:"seed_predicate_class,omitempty"`
	// EndpointLimit caps terminal endpoints admitted into endpoint-seeded search.
	EndpointLimit int64 `json:"endpoint_limit,omitempty"`
	// StateLimit caps reverse-search states admitted before falling back.
	StateLimit int64 `json:"state_limit,omitempty"`
	// HasFinalLimit reports whether the terminal projection has a row limit.
	HasFinalLimit bool `json:"has_final_limit,omitempty"`
	// ObservationMode describes the representation required by downstream consumers.
	ObservationMode ExpansionSearchObservationMode `json:"observation_mode"`
	// LogicalDirection supplies the logical direction input to the ExpansionSearchStrategyDecision contract.
	LogicalDirection string `json:"logical_direction"`
	// MinimumDepth is the inclusive lower expansion-depth bound.
	MinimumDepth int64 `json:"minimum_depth"`
	// MaximumDepth is the inclusive upper expansion-depth bound, or zero when unbounded.
	MaximumDepth int64 `json:"maximum_depth,omitempty"`
	// SelectionMode records whether selection was automatic or forced by tooling.
	SelectionMode string `json:"selection_mode"`
	// SelectorVersion identifies the policy version that ranked the candidates.
	SelectorVersion string `json:"selector_version"`
	// FallbackStrategy is used when the specialized candidate cannot be applied.
	FallbackStrategy ExpansionSearchStrategy `json:"fallback_strategy"`
	// FallbackReason explains why the specialized candidate was not selected.
	FallbackReason string `json:"fallback_reason"`
}

ExpansionSearchStrategyDecision records qualification and selection details for one variable expansion.

type ExpansionSuffixPushdownDecision 

type ExpansionSuffixPushdownDecision struct {
	// Target locates the variable expansion followed by the fixed suffix.
	Target TraversalStepTarget `json:"target"`
	// SuffixLength is the number of fixed traversal steps eligible for pushdown.
	SuffixLength int `json:"suffix_length"`
	// SuffixStartStep identifies the first fixed traversal step in the suffix.
	SuffixStartStep int `json:"suffix_start_step"`
	// SuffixEndStep identifies the final fixed traversal step in the suffix.
	SuffixEndStep int `json:"suffix_end_step"`
	// ApplySupplemental reports whether translation should emit the supplemental suffix-search branch.
	ApplySupplemental bool `json:"apply_supplemental"`
	// Reason explains why supplemental suffix search was enabled or withheld.
	Reason string `json:"reason,omitempty"`
	// PredicateAttachments lists predicates assigned to scopes within the fixed suffix.
	PredicateAttachments []PredicateAttachment `json:"predicate_attachments,omitempty"`
}

ExpansionSuffixPushdownDecision describes a fixed traversal suffix evaluated for supplemental search.

type FieldRequirement added in v1.0.0 

type FieldRequirement string
const (
	// FieldRequirementEntityID requires only the scalar entity identifier.
	FieldRequirementEntityID FieldRequirement = "entity_id"

	// FieldRequirementKinds requires the entity kind array in addition to identity.
	FieldRequirementKinds FieldRequirement = "kinds"

	// FieldRequirementProperties requires the entity property document in addition to identity.
	FieldRequirementProperties FieldRequirement = "properties"

	// FieldRequirementFullEntity requires the complete node or relationship composite.
	FieldRequirementFullEntity FieldRequirement = "full_entity"

	// FieldRequirementRelationshipIDs requires relationship IDs without hydrated relationship composites.
	FieldRequirementRelationshipIDs FieldRequirement = "relationship_ids"

	// FieldRequirementOrderedPathEdgeIDs requires edge IDs in path traversal order.
	FieldRequirementOrderedPathEdgeIDs FieldRequirement = "ordered_path_edge_ids"

	// FieldRequirementFullPath requires the complete hydrated path composite.
	FieldRequirementFullPath FieldRequirement = "full_path"
)

type FieldRequirementDecision added in v1.0.0 

type FieldRequirementDecision struct {
	// QueryPartIndex identifies the query part containing the analyzed binding.
	QueryPartIndex int `json:"query_part_index"`
	// Symbol is the Cypher binding whose representation requirements were analyzed.
	Symbol string `json:"symbol"`
	// Fields is the union of binding components required by all uses.
	Fields []FieldRequirement `json:"fields"`
	// Uses preserves the ordered evidence contributing to Fields.
	Uses []FieldRequirementUse `json:"uses"`
	// LastUse is the greatest use ordinal observed for the binding.
	LastUse int `json:"last_use"`
}

FieldRequirementDecision is analysis metadata only. Phase 6B consumes this staged information when it is safe to lower a composite binding to scalar state; recording it here intentionally does not change SQL semantics.

type FieldRequirementUse added in v1.0.0 

type FieldRequirementUse struct {
	// Ordinal orders this use relative to the other uses in its query part.
	Ordinal int `json:"ordinal"`
	// Fields lists the binding components consumed at this use.
	Fields []FieldRequirement `json:"fields"`
	// Internal reports whether the requirement is internal to translation rather than an external consumer.
	Internal bool `json:"internal,omitempty"`
}

FieldRequirementUse groups planner state that must remain consistent while analyzing field requirement use.

type InboundTraversalReversalRule added in v0.7.1 

type InboundTraversalReversalRule struct{}

InboundTraversalReversalRule reverses a qualifying multi-step traversal pattern so that the search is driven from the more selective terminal endpoint inward, rather than expanding outward from an unconstrained source through a leading unbounded variable-length expansion.

A pattern such as: 

MATCH p = (s:User)-[:MemberOf*0..]->(:Group)-[:AdminTo]->(d:Computer)
WHERE s.samaccountname =~ '(?i).*[ge]$' AND d.operatingsystem CONTAINS "WINDOWS SERVER"
RETURN p

is rewritten to drive from d:Computer inbound toward s:User by reversing the pattern element order and each relationship direction. The reversed pattern is flagged via PatternPart.PathDirectionReversed so path materialization can restore the original left-to-right order for RETURN p.

func (InboundTraversalReversalRule) Apply added in v0.7.1 

func (s InboundTraversalReversalRule) Apply(plan *Plan) (bool, error)

func (InboundTraversalReversalRule) Name added in v0.7.1 

func (s InboundTraversalReversalRule) Name() string

type LatePathMaterializationDecision 

type LatePathMaterializationDecision struct {
	// Target supplies the target input to the LatePathMaterializationDecision contract.
	Target TraversalStepTarget `json:"target"`
	// Mode identifies the mode.
	Mode LatePathMaterializationMode `json:"mode"`
}

LatePathMaterializationDecision records the planner choice made for late path materialization.

type LatePathMaterializationMode 

type LatePathMaterializationMode string
const (
	// LatePathMaterializationPathEdgeID carries a path as ordered edge IDs until hydration.
	LatePathMaterializationPathEdgeID LatePathMaterializationMode = "path_edge_id"

	// LatePathMaterializationExpansionPath carries recursive expansion path state until hydration.
	LatePathMaterializationExpansionPath LatePathMaterializationMode = "expansion_path"

	// LatePathMaterializationEdgeComposite defers hydration of an edge composite.
	LatePathMaterializationEdgeComposite LatePathMaterializationMode = "edge_composite"
)

type LimitPushdownDecision 

type LimitPushdownDecision struct {
	// Target supplies the target input to the LimitPushdownDecision contract.
	Target TraversalStepTarget `json:"target"`
	// Mode identifies the mode.
	Mode LimitPushdownMode `json:"mode"`
}

LimitPushdownDecision records the planner choice made for limit pushdown.

type LimitPushdownMode 

type LimitPushdownMode string
const (
	// LimitPushdownTraversalCTE applies a row limit inside an ordinary traversal CTE.
	LimitPushdownTraversalCTE LimitPushdownMode = "traversal_cte"

	// LimitPushdownShortestPathHarness applies a row limit inside a shortest-path harness.
	LimitPushdownShortestPathHarness LimitPushdownMode = "shortest_path_harness"
)

type LoweringDecision 

type LoweringDecision struct {
	// Name identifies the name.
	Name string `json:"name"`
}

LoweringDecision records the planner choice made for lowering.

type LoweringPlan 

type LoweringPlan struct {
	// ProjectionPruning records traversal fields that downstream clauses do not require.
	ProjectionPruning []ProjectionPruningDecision `json:"projection_pruning,omitempty"`
	// LatePathMaterialization records path values whose hydration can be deferred.
	LatePathMaterialization []LatePathMaterializationDecision `json:"late_path_materialization,omitempty"`
	// ExpandInto records traversal steps whose endpoints are both already bound.
	ExpandInto []ExpandIntoDecision `json:"expand_into,omitempty"`
	// TraversalDirection records planned logical direction changes.
	TraversalDirection []TraversalDirectionDecision `json:"traversal_direction,omitempty"`
	// ShortestPathStrategy records directional search choices for shortest-path steps.
	ShortestPathStrategy []ShortestPathStrategyDecision `json:"shortest_path_strategy,omitempty"`
	// ShortestPathFilter records endpoint filters selected for materialization.
	ShortestPathFilter []ShortestPathFilterDecision `json:"shortest_path_filter,omitempty"`
	// LimitPushdown records row limits that may safely constrain traversal work.
	LimitPushdown []LimitPushdownDecision `json:"limit_pushdown,omitempty"`
	// ExpansionSuffixPushdown records fixed suffixes considered for supplemental filtering, including withheld candidates.
	ExpansionSuffixPushdown []ExpansionSuffixPushdownDecision `json:"expansion_suffix_pushdown,omitempty"`
	// PredicatePlacement supplies the predicate placement input to the LoweringPlan contract.
	PredicatePlacement []PredicatePlacementDecision `json:"predicate_placement,omitempty"`
	// PatternPredicate records existence lowering selected for pattern predicates.
	PatternPredicate []PatternPredicatePlacementDecision `json:"pattern_predicate_placement,omitempty"`
	// CountStoreFastPath records counts answerable directly from graph statistics.
	CountStoreFastPath []CountStoreFastPathDecision `json:"count_store_fast_path,omitempty"`
	// ExactRangeExpansion records short fixed-depth ranges selected for unrolling.
	ExactRangeExpansion []ExactRangeExpansionDecision `json:"exact_range_expansion,omitempty"`
	// PathRelationshipPredicate records relationship quantifiers attached to carried path state.
	PathRelationshipPredicate []PathRelationshipPredicateDecision `json:"path_relationship_predicate,omitempty"`
	// AggregateTraversalCount records traversals lowered directly to aggregate counts.
	AggregateTraversalCount []AggregateTraversalCountDecision `json:"aggregate_traversal_count,omitempty"`
	// FieldRequirements records downstream representation needs for each analyzed binding.
	FieldRequirements []FieldRequirementDecision `json:"field_requirements,omitempty"`
	// ShortestPathExecutor records physical executor choices for shortest-path steps.
	ShortestPathExecutor []ShortestPathExecutorDecision `json:"shortest_path_executor,omitempty"`
	// ExpansionSearchStrategy records physical search choices for variable expansions.
	ExpansionSearchStrategy []ExpansionSearchStrategyDecision `json:"expansion_search_strategy,omitempty"`
	// EndpointResolution records planned-only bounded endpoint materialization for SP/ASP traversals.
	EndpointResolution []EndpointResolutionDecision `json:"endpoint_resolution,omitempty"`
	// TraversalPredicate records conservative locality and universality classifications.
	TraversalPredicate []TraversalPredicateDecision `json:"traversal_predicate,omitempty"`
}

LoweringPlan records lowering analyses and semantic or physical decisions for a query.

func BuildLoweringPlan 

func BuildLoweringPlan(query *cypher.RegularQuery, predicateAttachments []PredicateAttachment) (LoweringPlan, error)

BuildLoweringPlan analyzes a query and selects safe semantic and physical lowering decisions.

func (LoweringPlan) Decisions 

func (s LoweringPlan) Decisions() []LoweringDecision

Decisions returns one summary entry for each lowering category present in the plan.

func (LoweringPlan) Empty 

func (s LoweringPlan) Empty() bool

Empty reports whether the plan contains no lowering-analysis or decision entries.

type MatchClause 

type MatchClause struct {
	Index           int
	PatternCount    int
	WherePredicates int
}

type Optimizer 

type Optimizer struct {
	// contains filtered or unexported fields
}

func NewOptimizer 

func NewOptimizer(rules ...Rule) Optimizer

func (Optimizer) Optimize 

func (s Optimizer) Optimize(query *cypher.RegularQuery) (Plan, error)

Optimize preserves the historical ownership contract: the returned plan always owns its query independently of the caller's input.

func (Optimizer) OptimizeBorrowed added in v0.8.0 

func (s Optimizer) OptimizeBorrowed(query *cypher.RegularQuery) (Plan, error)

OptimizeBorrowed applies the optimizer without copying query until a rule needs to mutate it. See OptimizeBorrowed for ownership details.

type PathRelationshipPredicateDecision added in v0.7.0 

type PathRelationshipPredicateDecision struct {
	// Target supplies the target input to the PathRelationshipPredicateDecision contract.
	Target QuantifierTarget `json:"target"`
	// PathSymbol supplies the path symbol input to the PathRelationshipPredicateDecision contract.
	PathSymbol string `json:"path_symbol"`
	// BindingSymbol supplies the binding symbol input to the PathRelationshipPredicateDecision contract.
	BindingSymbol string `json:"binding_symbol"`
}

PathRelationshipPredicateDecision records the planner choice made for path relationship predicate.

type PathVariable 

type PathVariable struct {
	Symbol            string
	ClauseIndex       int
	PatternIndex      int
	NodeCount         int
	RelationshipCount int
	VariableLength    bool
	Dependencies      []string
}

type PatternPredicatePlacementDecision 

type PatternPredicatePlacementDecision struct {
	// Target supplies the target input to the PatternPredicatePlacementDecision contract.
	Target TraversalStepTarget `json:"target"`
	// Mode identifies the mode.
	Mode PatternPredicatePlacementMode `json:"mode"`
}

PatternPredicatePlacementDecision records the planner choice made for pattern predicate placement.

type PatternPredicatePlacementMode 

type PatternPredicatePlacementMode string
const (
	// PatternPredicatePlacementExistence lowers a pattern predicate as an existence test.
	PatternPredicatePlacementExistence PatternPredicatePlacementMode = "existence"
)

type PatternTarget 

type PatternTarget struct {
	// QueryPartIndex supplies the query part index input to the PatternTarget contract.
	QueryPartIndex int `json:"query_part_index"`
	// ClauseIndex supplies the clause index input to the PatternTarget contract.
	ClauseIndex int `json:"clause_index"`
	// PatternIndex supplies the pattern index input to the PatternTarget contract.
	PatternIndex int `json:"pattern_index"`
	// Predicate indicates whether predicate applies.
	Predicate bool `json:"predicate,omitempty"`
	// PredicateIndex supplies the predicate index input to the PatternTarget contract.
	PredicateIndex int `json:"predicate_index,omitempty"`
}

PatternTarget locates the query element affected by pattern.

func (PatternTarget) TraversalStep 

func (s PatternTarget) TraversalStep(stepIndex int) TraversalStepTarget

TraversalStep evaluates planner state needed for traversal step.

type Plan 

type Plan struct {
	Query                *cypher.RegularQuery
	Analysis             Analysis
	LoweringPlan         LoweringPlan
	Rules                []RuleResult
	PredicateAttachments []PredicateAttachment
	// contains filtered or unexported fields
}

func Optimize 

func Optimize(query *cypher.RegularQuery) (Plan, error)

func OptimizeBorrowed added in v0.8.0 

func OptimizeBorrowed(query *cypher.RegularQuery) (Plan, error)

OptimizeBorrowed optimizes query without copying it up front. The returned plan aliases query when no rewrite applies; rules must call EnsureMutable before modifying the tree. It is intended for callers that already own the input tree and can treat the returned plan as read-only.

func (*Plan) EnsureMutable added in v0.8.0 

func (s *Plan) EnsureMutable() *cypher.RegularQuery

EnsureMutable gives a rule an owned query before it changes the AST. It is intentionally idempotent so multiple applied rules share one copy.

type Predicate 

type Predicate struct {
	ClauseIndex     int
	ExpressionIndex int
	Dependencies    []string
}

type PredicateAttachment 

type PredicateAttachment struct {
	QueryPartIndex  int                      `json:"query_part_index"`
	RegionIndex     int                      `json:"region_index"`
	ClauseIndex     int                      `json:"clause_index"`
	ExpressionIndex int                      `json:"expression_index"`
	Scope           PredicateAttachmentScope `json:"scope"`
	BindingSymbols  []string                 `json:"binding_symbols"`
	Dependencies    []string                 `json:"dependencies"`
}

func AttachPredicates 

func AttachPredicates(analysis Analysis) []PredicateAttachment

type PredicateAttachmentRule 

type PredicateAttachmentRule struct{}

func (PredicateAttachmentRule) Apply 

func (s PredicateAttachmentRule) Apply(plan *Plan) (bool, error)

func (PredicateAttachmentRule) Name 

func (s PredicateAttachmentRule) Name() string

type PredicateAttachmentScope 

type PredicateAttachmentScope string
const (
	PredicateAttachmentScopeBinding PredicateAttachmentScope = "binding"
	PredicateAttachmentScopeRegion  PredicateAttachmentScope = "region"
)

type PredicatePlacementDecision 

type PredicatePlacementDecision struct {
	// Target supplies the target input to the PredicatePlacementDecision contract.
	Target TraversalStepTarget `json:"target"`
	// Attachment supplies the attachment input to the PredicatePlacementDecision contract.
	Attachment PredicateAttachment `json:"attachment"`
	// Placement supplies the placement input to the PredicatePlacementDecision contract.
	Placement PredicateAttachmentScope `json:"placement"`
}

PredicatePlacementDecision records the planner choice made for predicate placement.

type ProjectionPruningDecision 

type ProjectionPruningDecision struct {
	// Target supplies the target input to the ProjectionPruningDecision contract.
	Target TraversalStepTarget `json:"target"`
	// ReferencedSymbols supplies the referenced symbols input to the ProjectionPruningDecision contract.
	ReferencedSymbols []string `json:"referenced_symbols,omitempty"`
	// PatternBindingReferenced indicates whether pattern binding referenced applies.
	PatternBindingReferenced bool `json:"pattern_binding_referenced,omitempty"`
	// OmitLeftNode indicates whether omit left node applies.
	OmitLeftNode bool `json:"omit_left_node,omitempty"`
	// OmitRelationship indicates whether omit relationship applies.
	OmitRelationship bool `json:"omit_relationship,omitempty"`
	// OmitRightNode indicates whether omit right node applies.
	OmitRightNode bool `json:"omit_right_node,omitempty"`
	// OmitPathBinding indicates whether omit path binding applies.
	OmitPathBinding bool `json:"omit_path_binding,omitempty"`
}

ProjectionPruningDecision records the planner choice made for projection pruning.

type QuantifierTarget added in v0.7.0 

type QuantifierTarget struct {
	// QueryPartIndex supplies the query part index input to the QuantifierTarget contract.
	QueryPartIndex int `json:"query_part_index"`
	// QuantifierIndex supplies the quantifier index input to the QuantifierTarget contract.
	QuantifierIndex int `json:"quantifier_index"`
}

QuantifierTarget locates the query element affected by quantifier.

type QueryPart 

type QueryPart struct {
	Index                  int
	Kind                   QueryPartKind
	Regions                []Region
	Barriers               []Barrier
	ProjectionDependencies []string
}

type QueryPartKind 

type QueryPartKind string
const (
	QueryPartKindSingle QueryPartKind = "single"
	QueryPartKindMulti  QueryPartKind = "multi"
)

type Region 

type Region struct {
	QueryPartIndex     int
	StartClause        int
	EndClause          int
	Clauses            []MatchClause
	Bindings           []Binding
	BindingOccurrences []Binding
	PathVariables      []PathVariable
	Predicates         []Predicate
}

type Rule 

type Rule interface {
	Name() string
	Apply(*Plan) (bool, error)
}

func DefaultRules 

func DefaultRules() []Rule

type RuleResult 

type RuleResult struct {
	Name    string `json:"name"`
	Applied bool   `json:"applied"`
}

type SelectivityModel 

type SelectivityModel struct {
	// contains filtered or unexported fields
}

func NewSelectivityModel 

func NewSelectivityModel(bindings BindingLookup) SelectivityModel

func (SelectivityModel) EndpointSelectivity 

func (s SelectivityModel) EndpointSelectivity(expression pgsql.Expression, bound, hasPreviousFrameBinding bool) (int, error)

func (SelectivityModel) Measure 

func (s SelectivityModel) Measure(expression pgsql.Expression) (int, error)

func (SelectivityModel) ShouldFlipTraversalDirection 

func (s SelectivityModel) ShouldFlipTraversalDirection(leftBound, rightBound bool, leftExpression, rightExpression pgsql.Expression) (bool, error)

type ShortestPathEligibilityFact added in v1.0.0 

type ShortestPathEligibilityFact struct {
	// Name identifies the qualification check.
	Name string `json:"name"`
	// Eligible reports whether the candidate passed the named check.
	Eligible bool `json:"eligible"`
}

ShortestPathEligibilityFact records one named qualification check for an executor candidate.

type ShortestPathExecutor added in v1.0.0 

type ShortestPathExecutor string

func (ShortestPathExecutor) ExecutionBoundary added in v1.0.0 

func (s ShortestPathExecutor) ExecutionBoundary() string

ExecutionBoundary reports the SQL boundary represented by the executor identity. Benchmark and promotion artifacts must match this value.

func (ShortestPathExecutor) Scheduler added in v1.0.0 

func (s ShortestPathExecutor) Scheduler() ShortestPathScheduler

Scheduler reports the stable frontier scheduler associated with this executor.

type ShortestPathExecutorDecision added in v1.0.0 

type ShortestPathExecutorDecision struct {
	// Target locates the traversal step governed by this decision.
	Target TraversalStepTarget `json:"target"`
	// Family names the executor-selection family that produced the decision.
	Family string `json:"family"`
	// PlannedCandidates lists the executors considered in preference order.
	PlannedCandidates []ShortestPathExecutor `json:"planned_candidates"`
	// SelectedExecutor is the executor chosen after qualification.
	SelectedExecutor ShortestPathExecutor `json:"selected_executor"`
	// ExecutionBoundary distinguishes inline statement SQL from stored helper
	// execution. Promotion evidence must match this boundary exactly.
	ExecutionBoundary string `json:"execution_boundary"`
	// Scheduler identifies the selected executor's frontier scheduling policy.
	Scheduler ShortestPathScheduler `json:"scheduler,omitempty"`
	// ObservationMode describes how downstream clauses consume the shortest path.
	ObservationMode ShortestPathObservationMode `json:"observation_mode"`
	// Direction is the logical direction of the traversal.
	Direction graph.Direction `json:"direction"`
	// PhysicalExpansion identifies which stored edge endpoint advances the search.
	PhysicalExpansion ShortestPathPhysicalExpansion `json:"physical_expansion"`
	// RelationshipKindCount is the number of statically resolved relationship kinds.
	RelationshipKindCount int `json:"relationship_kind_count"`
	// UntypedRelationship reports whether the pattern omitted relationship kinds.
	UntypedRelationship bool `json:"untyped_relationship"`
	// TopologyClassification summarizes logical direction, physical direction, and depth.
	TopologyClassification ShortestPathTopologyClassification `json:"topology_classification"`
	// Eligibility records each qualification check and its result.
	Eligibility []ShortestPathEligibilityFact `json:"eligibility"`
	// StructurallyEligible reports whether the query shape can use the candidate executor.
	StructurallyEligible bool `json:"structurally_eligible"`
	// StaticallyEligible reports whether known literals and kinds satisfy executor constraints.
	StaticallyEligible bool `json:"statically_eligible"`
	// MinimumDepth is the inclusive lower traversal-depth bound.
	MinimumDepth int64 `json:"minimum_depth"`
	// MaximumDepth is the inclusive upper traversal-depth bound.
	MaximumDepth int64 `json:"maximum_depth"`
	// MaximumDepthSource records whether MaximumDepth was explicit syntax or
	// supplied by the existing traversal policy.
	MaximumDepthSource ShortestPathMaximumDepthSource `json:"maximum_depth_source"`
	// StateLimit caps state admitted by bounded experimental executors.
	StateLimit int64 `json:"state_limit,omitempty"`
	// FrontierLimit caps current and queued frontier rows independently of seen state.
	FrontierLimit int64 `json:"frontier_limit,omitempty"`
	// PredecessorLimit caps retained witness predecessor rows independently of discovery state.
	PredecessorLimit int64 `json:"predecessor_limit,omitempty"`
	// EnumerationLimit caps distinct ordered all-shortest-path arrays before exact fallback.
	EnumerationLimit int64 `json:"enumeration_limit,omitempty"`
	// OutputBytesLimit caps staged all-shortest-path array bytes before exact fallback.
	OutputBytesLimit int64 `json:"output_bytes_limit,omitempty"`
	// SelectorVersion identifies the policy version that ranked the candidates.
	SelectorVersion string `json:"selector_version"`
	// SelectionMode records whether selection was automatic or forced by tooling.
	SelectionMode string `json:"selection_mode"`
	// FallbackExecutor is used when the preferred candidate cannot be applied.
	FallbackExecutor ShortestPathExecutor `json:"fallback_executor"`
	// FallbackReason explains why the preferred candidate was not selected.
	FallbackReason string `json:"fallback_reason"`
	// ExperimentalWinner reports whether an experimental candidate beat the incumbent.
	ExperimentalWinner bool `json:"experimental_winner,omitempty"`
}

ShortestPathExecutorDecision records either a qualified static executor or the incumbent fallback, keeping every eligibility and fallback fact visible.

type ShortestPathFilterDecision 

type ShortestPathFilterDecision struct {
	// Target supplies the target input to the ShortestPathFilterDecision contract.
	Target TraversalStepTarget `json:"target"`
	// Mode identifies the mode.
	Mode ShortestPathFilterMode `json:"mode"`
	// Reason supplies the reason input to the ShortestPathFilterDecision contract.
	Reason string `json:"reason,omitempty"`
}

ShortestPathFilterDecision records the planner choice made for shortest path filter.

type ShortestPathFilterMode 

type ShortestPathFilterMode string
const (
	// ShortestPathFilterTerminal materializes candidate terminal IDs independently of roots.
	ShortestPathFilterTerminal ShortestPathFilterMode = "terminal"

	// ShortestPathFilterEndpointPair materializes admissible root-terminal ID pairs.
	ShortestPathFilterEndpointPair ShortestPathFilterMode = "endpoint_pair"
)

type ShortestPathMaximumDepthSource added in v1.0.0 

type ShortestPathMaximumDepthSource string

ShortestPathMaximumDepthSource distinguishes an explicit Cypher upper bound from an absent maximum for a syntax-open range. 

const (
	// ShortestPathMaximumDepthExplicit identifies an upper bound written in the query.
	ShortestPathMaximumDepthExplicit ShortestPathMaximumDepthSource = "explicit"

	// ShortestPathMaximumDepthUnbounded preserves an absent Cypher maximum.
	ShortestPathMaximumDepthUnbounded ShortestPathMaximumDepthSource = "unbounded"

	// ShortestPathMaximumDepthPolicyDefault is retained for historical diagnostic consumers.
	// New open ranges report ShortestPathMaximumDepthUnbounded.
	ShortestPathMaximumDepthPolicyDefault ShortestPathMaximumDepthSource = "policy_default"
)

type ShortestPathObservationMode added in v1.0.0 

type ShortestPathObservationMode string
const (
	// ShortestPathObservationDistance indicates that only shortest-path length is consumed.
	ShortestPathObservationDistance ShortestPathObservationMode = "distance"

	// ShortestPathObservationOnePath indicates that one shortest-path witness is consumed.
	ShortestPathObservationOnePath ShortestPathObservationMode = "one_path"

	// ShortestPathObservationAllPaths indicates that every shortest-path witness is consumed.
	ShortestPathObservationAllPaths ShortestPathObservationMode = "all_paths"

	// ShortestPathObservationUnknown indicates that analysis could not classify downstream path use.
	ShortestPathObservationUnknown ShortestPathObservationMode = "unknown"
)

type ShortestPathPhysicalExpansion added in v1.0.0 

type ShortestPathPhysicalExpansion string
const (
	// ShortestPathPhysicalExpansionStartID joins recursive expansion through each edge's start ID.
	ShortestPathPhysicalExpansionStartID ShortestPathPhysicalExpansion = "start_id"

	// ShortestPathPhysicalExpansionEndID joins recursive expansion through each edge's end ID.
	ShortestPathPhysicalExpansionEndID ShortestPathPhysicalExpansion = "end_id"
)

type ShortestPathScheduler added in v1.0.0 

type ShortestPathScheduler string

ShortestPathScheduler identifies the frontier scheduling policy used by a shortest-path executor independently of its result-observation contract. 

const (
	// ShortestPathSchedulerSingleEndedLevel expands one complete level from a single frontier.
	ShortestPathSchedulerSingleEndedLevel ShortestPathScheduler = "single_ended_level"

	// ShortestPathSchedulerStrictAlternatingNode alternates one node expansion from each frontier.
	ShortestPathSchedulerStrictAlternatingNode ShortestPathScheduler = "strict_alternating_node"

	// ShortestPathSchedulerSmallerCurrentLevel expands the smaller of the two current frontier levels.
	ShortestPathSchedulerSmallerCurrentLevel ShortestPathScheduler = "smaller_current_level"
)

type ShortestPathStrategy 

type ShortestPathStrategy string
const (
	// ShortestPathStrategyBidirectional searches simultaneously from both endpoints.
	ShortestPathStrategyBidirectional ShortestPathStrategy = "bidirectional"

	// ShortestPathStrategyUnidirectional searches from one endpoint toward the other.
	ShortestPathStrategyUnidirectional ShortestPathStrategy = "unidirectional"
)

type ShortestPathStrategyDecision 

type ShortestPathStrategyDecision struct {
	// Target supplies the target input to the ShortestPathStrategyDecision contract.
	Target TraversalStepTarget `json:"target"`
	// Strategy supplies the strategy input to the ShortestPathStrategyDecision contract.
	Strategy ShortestPathStrategy `json:"strategy"`
	// Reason supplies the reason input to the ShortestPathStrategyDecision contract.
	Reason string `json:"reason,omitempty"`
}

ShortestPathStrategyDecision records the planner choice made for shortest path strategy.

type ShortestPathTopologyClassification added in v1.0.0 

type ShortestPathTopologyClassification string
const (
	// ShortestPathTopologyPhysicalOutbound classifies traversal aligned with stored edge direction.
	ShortestPathTopologyPhysicalOutbound ShortestPathTopologyClassification = "physical_outbound"

	// ShortestPathTopologyPhysicalInboundShallow classifies a shallow traversal against stored edge direction.
	ShortestPathTopologyPhysicalInboundShallow ShortestPathTopologyClassification = "physical_inbound_shallow"

	// ShortestPathTopologyPhysicalInboundDeep classifies a deep traversal against stored edge direction.
	ShortestPathTopologyPhysicalInboundDeep ShortestPathTopologyClassification = "physical_inbound_deep"

	// ShortestPathTopologyDirectionless classifies traversal that may follow either stored direction.
	ShortestPathTopologyDirectionless ShortestPathTopologyClassification = "directionless"
)

type TraversalDirectionDecision 

type TraversalDirectionDecision struct {
	// Target supplies the target input to the TraversalDirectionDecision contract.
	Target TraversalStepTarget `json:"target"`
	// Flip indicates whether flip applies.
	Flip bool `json:"flip,omitempty"`
	// Reason supplies the reason input to the TraversalDirectionDecision contract.
	Reason string `json:"reason,omitempty"`
}

TraversalDirectionDecision records the planner choice made for traversal direction.

type TraversalPredicateClass added in v1.0.0 

type TraversalPredicateClass string

TraversalPredicateClass identifies the strongest safe placement property proven from syntax. Unsupported path forms deliberately remain conservative. 

const (
	// TraversalPredicateClassStepLocalNode reserves the stable protocol value used to recognize traversal predicate class step local node across artifacts and executions.
	TraversalPredicateClassStepLocalNode TraversalPredicateClass = "step_local_node"

	// TraversalPredicateClassStepLocalRelationship reserves the stable protocol value used to recognize traversal predicate class step local relationship across artifacts and executions.
	TraversalPredicateClassStepLocalRelationship TraversalPredicateClass = "step_local_relationship"

	// TraversalPredicateClassUniversalAllNodes reserves the stable protocol value used to recognize traversal predicate class universal all nodes across artifacts and executions.
	TraversalPredicateClassUniversalAllNodes TraversalPredicateClass = "universal_all_nodes"

	// TraversalPredicateClassUniversalNoneNodes reserves the stable protocol value used to recognize traversal predicate class universal none nodes across artifacts and executions.
	TraversalPredicateClassUniversalNoneNodes TraversalPredicateClass = "universal_none_nodes"

	// TraversalPredicateClassUniversalAllRelationships reserves the stable protocol value used to recognize traversal predicate class universal all relationships across artifacts and executions.
	TraversalPredicateClassUniversalAllRelationships TraversalPredicateClass = "universal_all_relationships"

	// TraversalPredicateClassUniversalNoneRelationships reserves the stable protocol value used to recognize traversal predicate class universal none relationships across artifacts and executions.
	TraversalPredicateClassUniversalNoneRelationships TraversalPredicateClass = "universal_none_relationships"

	// TraversalPredicateClassWholePath reserves the stable protocol value used to recognize traversal predicate class whole path across artifacts and executions.
	TraversalPredicateClassWholePath TraversalPredicateClass = "whole_path"

	// TraversalPredicateClassUnsupported reserves the stable protocol value used to recognize traversal predicate class unsupported across artifacts and executions.
	TraversalPredicateClassUnsupported TraversalPredicateClass = "unsupported"
)

type TraversalPredicateDecision added in v1.0.0 

type TraversalPredicateDecision struct {
	// Target supplies the target input to the TraversalPredicateDecision contract.
	Target TraversalStepTarget `json:"target"`
	// PredicateIndex supplies the predicate index input to the TraversalPredicateDecision contract.
	PredicateIndex int `json:"predicate_index"`
	// Source supplies the source input to the TraversalPredicateDecision contract.
	Source string `json:"source"`
	// Class supplies the class input to the TraversalPredicateDecision contract.
	Class TraversalPredicateClass `json:"class"`
	// PathSymbol supplies the path symbol input to the TraversalPredicateDecision contract.
	PathSymbol string `json:"path_symbol,omitempty"`
	// BindingSymbol supplies the binding symbol input to the TraversalPredicateDecision contract.
	BindingSymbol string `json:"binding_symbol,omitempty"`
	// ReferencedSymbols supplies the referenced symbols input to the TraversalPredicateDecision contract.
	ReferencedSymbols []string `json:"referenced_symbols,omitempty"`
	// PlannedCandidates supplies the planned candidates input to the TraversalPredicateDecision contract.
	PlannedCandidates []TraversalPredicatePlan `json:"planned_candidates"`
	// CandidatePlan supplies the candidate plan input to the TraversalPredicateDecision contract.
	CandidatePlan TraversalPredicatePlan `json:"candidate_plan,omitempty"`
	// SelectedPlan supplies the selected plan input to the TraversalPredicateDecision contract.
	SelectedPlan TraversalPredicatePlan `json:"selected_plan"`
	// FallbackPlan supplies the fallback plan input to the TraversalPredicateDecision contract.
	FallbackPlan TraversalPredicatePlan `json:"fallback_plan"`
	// EligibilityFacts supplies the eligibility facts input to the TraversalPredicateDecision contract.
	EligibilityFacts []TraversalPredicateEligibilityFact `json:"eligibility_facts"`
	// StructurallyEligible indicates whether structurally eligible applies.
	StructurallyEligible bool `json:"structurally_eligible"`
	// StaticallyEligible indicates whether statically eligible applies.
	StaticallyEligible bool `json:"statically_eligible"`
	// SelectionMode identifies the selection mode.
	SelectionMode string `json:"selection_mode"`
	// ClassifierVersion identifies the schema version for classifier version.
	ClassifierVersion string `json:"classifier_version"`
	// FallbackReason supplies the fallback reason input to the TraversalPredicateDecision contract.
	FallbackReason string `json:"fallback_reason"`
}

TraversalPredicateDecision records one predicate relevant to a variable traversal. It never authorizes placement by itself.

type TraversalPredicateEligibilityFact added in v1.0.0 

type TraversalPredicateEligibilityFact struct {
	// Name identifies the name.
	Name string `json:"name"`
	// Eligible indicates whether eligible applies.
	Eligible bool `json:"eligible"`
}

TraversalPredicateEligibilityFact records one conservative classification or placement qualification.

type TraversalPredicatePlan added in v1.0.0 

type TraversalPredicatePlan string

TraversalPredicatePlan separates planned step evaluation from the exact incumbent predicate placement that remains selected. 

const (
	// TraversalPredicatePlanIncumbent reserves the stable protocol value used to recognize traversal predicate plan incumbent across artifacts and executions.
	TraversalPredicatePlanIncumbent TraversalPredicatePlan = "TRAVERSAL-PREDICATE-INCUMBENT"

	// TraversalPredicatePlanStep reserves the stable protocol value used to recognize traversal predicate plan step across artifacts and executions.
	TraversalPredicatePlanStep TraversalPredicatePlan = "TRAVERSAL-PREDICATE-STEP"
)

type TraversalStepTarget 

type TraversalStepTarget struct {
	// QueryPartIndex supplies the query part index input to the TraversalStepTarget contract.
	QueryPartIndex int `json:"query_part_index"`
	// ClauseIndex supplies the clause index input to the TraversalStepTarget contract.
	ClauseIndex int `json:"clause_index"`
	// PatternIndex supplies the pattern index input to the TraversalStepTarget contract.
	PatternIndex int `json:"pattern_index"`
	// Predicate indicates whether predicate applies.
	Predicate bool `json:"predicate,omitempty"`
	// PredicateIndex supplies the predicate index input to the TraversalStepTarget contract.
	PredicateIndex int `json:"predicate_index,omitempty"`
	// StepIndex supplies the step index input to the TraversalStepTarget contract.
	StepIndex int `json:"step_index"`
}

TraversalStepTarget locates the query element affected by traversal step.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.