Argo Queries

Overview

The Argo query engine combines semantic search (Pinecone) with graph traversal (Neo4j) in a single query language. Results are ranked by combining semantic similarity scores with path length.

API Endpoint

POST /query
Content-Type: application/json
Authorization: Bearer <token>

{
  "path": "\"medical college\" -[*]{,4}-> type:file",
  "k": 25,
  "expand": "preview"
}

Request Parameters

Parameter	Type	Default	Description
`path`	string	required	Argo query string
`k`	number	25	Maximum results to return (1-100)
`k_explore`	number	k * 3	Beam width for exploration
`collection`	string	-	Scope query to a collection PI
`expand`	string	"preview"	Entity expansion mode

Expansion Modes

Value	Description
(omitted) or `"preview"`	Lightweight preview data (label, timestamps, truncated description)
`"full"`	Complete entity manifest (all properties, relationships, version info)
`"none"`	No expansion - Pinecone metadata only (fastest)

Query Syntax

[SCOPE_PREFIX] ENTRY_POINT [ENTRY_FILTER] [-[RELATION]{DEPTH}-> TARGET_FILTER]...

Scope Prefixes

Control where semantic search looks for entry points. Default is discovery mode.

Prefix	Description	Example
(none)	Discovery mode (default) - find relevant collections, then search within each	`"medical notes"`
`@:collections`	Search for collections themselves	`@:collections "columbia archives"`
`@:collection(id)`	Search within a specific collection	`@:collection(01JCOLL123) "meeting"`
`@:discover`	Explicit discovery mode	`@:discover "research papers"`
`@:public`	Search public domain only	`@:public "orphaned data"`

Note: Graph traversal (hops) is always cross-collection regardless of scope.

Entry Points

Syntax	Description	Example
`"text"`	Semantic search	`"george washington"`
`@id`	Exact entity ID	`@01KE4ZY69F9R40E88PK9S0TQRQ`
`type:X`	All entities of type	`type:person`
`type:X ~ "text"`	Semantic search within type	`type:person ~ "physician"`

Entry Filters

After the entry point, you can add a filter before any traversal:

"search text" type:person                    # Filter entry results by type
"alice" type:person,user                     # Multi-type filter (OR)

Edge Syntax (Hops)

Syntax	Direction
`-[*]->`	Outgoing
`<-[*]-`	Incoming
`<-[*]->`	Both directions (bidirectional)

Depth Ranges

Syntax	Meaning
`-[*]->`	Exactly 1 hop (default)
`-[*]{3}->`	Exactly 3 hops
`-[*]{,4}->`	1 to 4 hops
`-[*]{2,4}->`	2 to 4 hops
`-[*]{2,}->`	2 or more hops (up to default max)

Relationship Types

Syntax	Meaning
`-[*]->`	Any relationship type (wildcard)
`-[contains]->`	Specific relationship type
`-[contains,references]->`	Multiple relationship types (OR)

Target Filters

After each hop, specify what to match:

Syntax	Description
`type:X`	Filter by entity type
`type:X,Y`	Multiple types (OR)
`@id`	Match exact entity ID
`"text"`	Semantic search filter
`type:X ~ "text"`	Type + semantic filter

Examples

Basic Semantic Search

"Ahab's obsession"

Find entities matching the text query (discovery mode).

Semantic Search with Type Filter

"Ishmael" type:person

Find person entities matching "Ishmael".

Multi-Type Filter

"documents" type:file,document,chapter

Find entities of any of these types matching "documents".

Type with Semantic Modifier

type:person ~ "physician"

Find person entities semantically similar to "physician".

Graph Traversal from Semantic Entry

"Queequeg" -[*]{,4}-> type:chapter

Find entities matching "Queequeg", then traverse 1-4 hops of any relationship type to reach chapter entities.

Exact ID Entry Point

@01KFNR81RMVAX2BBMMBW51V97D -[*]{,2}-> type:person

Start from a specific entity, traverse 1-2 hops to find person entities.

Specific Relationship Type

@01KFNR81RMVAX2BBMMBW51V97D -[contains]{,3}-> type:file

Follow only "contains" relationships to find files.

Scoped Collection Search

@:collection(01JCOLL123) "faculty meeting" -[*]{,2}-> type:file

Search within a specific collection, then traverse to find related files.

Bidirectional Traversal

"alice" <-[*]{,3}-> type:document

Find entities related to "alice" in either direction.

Incoming Relationships

"important file" <-[references]- type:person

Find person entities that reference the matched entities.

Response Shape

{
  "results": [
    {
      "entity": {
        "pi": "01KE4ZY69F9R40E88PK9S0TQRQ",
        "type": "file",
        "label": "Theory of Relativity.pdf",
        "collection_pi": "01JCOLL_RESEARCH",
        "preview_data": {
          "id": "01KE4ZY69F9R40E88PK9S0TQRQ",
          "type": "file",
          "label": "Theory of Relativity.pdf",
          "description_preview": "Seminal paper on special and general relativity...",
          "created_at": "2025-01-10T08:00:00.000Z",
          "updated_at": "2025-01-10T08:00:00.000Z"
        }
      },
      "path": [
        {
          "entity": "01KPERSON_EINSTEIN",
          "label": "Albert Einstein",
          "type": "person",
          "score": 0.92,
          "preview_data": { ... }
        },
        { "edge": "authored", "direction": "outgoing" }
      ],
      "score": 0.89
    }
  ],
  "metadata": {
    "query": "\"einstein\" -[*]{,2}-> type:file",
    "hops": 1,
    "k": 25,
    "k_explore": 75,
    "total_candidates_explored": 150,
    "execution_time_ms": 342
  }
}

Query vs Graph Endpoints

Endpoint	Use Case
`POST /query`	Semantic search + graph traversal with relevance-ranked results
`POST /graph/reachable`	Exhaustive graph exploration from known entities (no ranking)
`POST /graph/paths`	Find all shortest paths between two entity sets

Use POST /query when you want results ranked by semantic relevance combined with graph distance. Use the /graph/* endpoints when you need comprehensive exploration from known entity IDs.

Query Components Reference

Component	Syntax	Example
Scope prefix	`@:name` or `@:name(param)`	`@:collection(01JCOLL123)`
Semantic entry	`"query text"`	`"whale hunting"`
ID entry	`@<entity_id>`	`@01JENTITY...`
Type entry	`type:<type>`	`type:person`
Type + semantic	`type:X ~ "text"`	`type:person ~ "doctor"`
Traversal out	`-[predicate]{min,max}->`	`-[*]{,4}->`
Traversal in	`<-[predicate]{min,max}-`	`<-[contains]-`
Traversal both	`<-[predicate]{min,max}->`	`<-[*]{,2}->`
Any predicate	`*`	`-[*]{,2}->`
Named predicate	`name` or `a,b,c`	`-[contains,references]->`
Depth range	`{min,max}`	`{1,3}`
Type filter	`type:X` or `type:X,Y`	`type:file,document`

On this page