Search DSL

This is the reference for SearchRequest — the request shape used by every search call into a Curiosity Workspace, whether from the UI, a custom endpoint, or an external integration. For the conceptual model see Core concepts → Search model.

Request lifecycle

var request = new SearchRequest("MacBook Air")
    .WithTypesFacet("SupportCase", "Device")
    .WithFuzziness(1);

var result = await Graph.CreateSearchAsync(request);
return result;

The request describes what to find, the graph executes it, and a SearchResult comes back. There is no separate "execute" step — passing the request to CreateSearchAsync runs it.

Request fields

Query

Type scope

BeforeTypesFacet is the more efficient option for "I always want only SupportCases here." TypesFacet is the right choice when the user is choosing the scope from the UI.

Target set

These restrict the search to nodes computed elsewhere — typically by a graph query — and are how you implement "search within context."

Facets

Each facet kind is a Dictionary<string, …> keyed by field/edge name.

Helper methods on SearchRequest (SetTimestampFacet, SetTimeFacet, …) wrap the dictionary form for common cases.

Sort and ranking

Vector / hybrid search

Related-result handling

Behaviour flags

Pagination

There is no Page/Offset/Limit on the request itself. Result-count control lives on the query that wraps the search, not the request:

var result = await Graph.CreateSearchAsync(request);
var page   = result.Results.Skip(50).Take(50);          // client-side window
// or, when chaining into a graph query:
var top    = Q().FromSearch(request).Skip(50).Take(50).Emit();

Workspace queries have a default limit of 50 nodes. If you want more, set .Take(n) on the wrapping query — there is no implicit upper bound but very large pages should use cursor-style pagination (carry the last-seen UID as ExcludeUIDs and re-query).

Response shape

public class SearchResult
{
    public SearchRequest             Request;
    public UID128                    QueryCache;
    public UID128                    SearchQueryUID;
    public string                    Count;
    public SearchStats               Stats;
    public ReadOnlyArray<SearchHit>  Results;
    public ReadOnlyArray<UID128>     ResultUIDs;
    public string                    TotalElapsedMilliseconds;
    public string                    Highlight;
    public bool                      Incomplete;
    public bool                      StillIndexing;
    public string                    ProCount;
}

SearchHit carries score, highlights, the resolved Node, child-hit pointers, and a FromVectorSearch flag so you can tell which retrieval branch produced the hit:

public class SearchHit
{
    public float        Score;
    public bool         Pinned;
    public bool         FromVectorSearch;
    public Node         Node;
    public TextAndUID[] Highlights;
    public UID128       SearchQueryUID;
    public ChildHit[]   ChildHits;
}

SearchStats gives you a per-request observability snapshot:

public class SearchStats
{
    public float                 ElapsedMilliseconds;
    public int                   TouchedNodes;
    public int                   TouchedEdges;
    public bool                  RestrictedNodesFilteredOut;
    public ReadOnlyArray<string> DetailedStats;
}

RestrictedNodesFilteredOut is true when ACL enforcement dropped hits before they reached the user — useful for distinguishing "no results" from "no results you can see." See Permission-aware retrieval.

Common patterns

Search within a graph context

var request = new SearchRequest("screen flicker")
    .WithTypesFacet("SupportCase")
    .WithTargetQuery(Q().StartAt("Manufacturer", "Apple").Out("Device").In("ForDevice"));

var result = await Graph.CreateSearchAsync(request);

Hybrid keyword + vector

var request = new SearchRequest("battery drains overnight")
    .WithTypesFacet("SupportCase");
request.VectorSearchTypes = new[] { "SupportCase" };
request.VectorSearchMode  = VectorSearchMode.Hybrid;

var result = await Graph.CreateSearchAsync(request);

Permission-scoped search

var result = await Graph.CreateSearchAsUserAsync(request, userId);

CreateSearchAsUserAsync is the permission-aware variant — it applies the user's ACL graph before scoring. See Access control model.

Error semantics

The search endpoint surfaces failures as standard HTTP / token errors at the transport layer. Logical issues — unknown types, missing facet fields, ACL-filtered empties — come back as a normal SearchResult with Results.Length == 0 and signal:

• Incomplete == true — the query was cut off (typically a timeout). Results are still valid but partial.
• StillIndexing == true — at least one matching field is still being built. Re-run the query later for completeness.
• RestrictedNodesFilteredOut == true — hits were removed by ACL.

For the catalog of error codes returned by REST/RPC calls (auth, schema, quota, etc.), see Error codes.

Related pages

• Core concepts → Search model
• Search → Ranking tuning
• Search → Hybrid search
• REST API