Keyword Syntax for Magic Predicate | AllegroGraph 9.0.1
Author: Franz Incorporated

remark -- indent-tabs-mode: nil; -- }

Copyright (c) 2005 - 2026 Franz, Incorporated
Last updated 27 May 2026 at 10:34

# AllegroGraph 9.0.1 Keyword Syntax for Magic Predicates

- Documentation Index
  - Release Notes
  - Quick Start
  - SSL/TLS Quick Start
  - Introduction
  - Setup and Configuration
    - Download
    - Server Installation
    - Server Configuration and Control
    - WebView
    - Database Upgrading
    - Managing Users
  - Server Management
    - Performance Tuning
    - Deleting Duplicate Triples
    - Purging Deleted Triples
    - Auditing
    - Managing Users
    - Replication
    - Point-in-Time Recovery
    - Transaction Log Archiving
    - Security Overview
    - Security Implementation
  - Tools
    - agtool
    - Data Loading
    - Data Export
    - Backup and Restore
    - Querying
    - RDFS++
    - Materializer
    - Event Scheduler
    - SHACL
  - Details
    - Triple Indices
    - Freetext Indices
    - Encoded IDs
    - Connection Pooling
    - N-dimensional Geospatial Overview
    - 2-D Geospatial
    - Temporal
    - Social Network
    - JavaScript
    - Datatypes
    - Data Conversion (Rapper)
    - Stored Procedures
    - Triple Attributes
    - Lineparse Format
  - Querying
    - SPARQL documentation summary
    - SPARQL Reference
    - SPIN
    - SPARQL Magic Properties
    - Prolog
  - 3rd-party tools
    - Solr text Indices
    - MongoDB integration
    - TopBraid Composer Plugin
    - Cloudera
  - Client APIs
    - Gruff
    - GraphTalker
    - REST/HTTP interface
    - HTTP reference
    - Javadocs (Sesame and Jena)
    - Python API
    - Lisp Reference
    - JavaScript
  - Tutorials
    - N-dimensional Geospatial
    - SPARQL Tutorial
    - Java Sesame
    - Java Jena
    - Python Sesame
    - Lisp
    - Prolog
    - More...
  - Other
    - Conferences and Seminars
    - Source Code on Github
    - Amazon EC2
    - Copyrights
  - Franz, Inc.

- The Purpose of Keyword Syntax
- How Keyword Syntax Works
- A Note on Namespaces
- Examples Using Keyword Syntax
- LLM Predicates Accepting Keyword Syntax

Documentation Index

## The Purpose of Keyword Syntax

Keyword syntax offers an elegant way to write queries with Allegrograph Magic Predicates, when the predicate has a large and unwieldy number of variables, while maintaining compatibility with standard SPARQL syntax.

Currently these three LLM magic predicates accept keyword syntax: llm:nearestNeighbor, llm:askMyDocuments and llm:chatState.

And the SNA magic property sna:communityLeiden accepts keywords as well.

Here is how keywords work with magic predicates. The syntax provided for the magic predicate llm:nearestNeigbor is

    (?uri ?score ?originalText ?pred ?type) llm:nearestNeighbor (?text ?vectorRepoSpec ?topN ?minScore ?selector ?useClustering)

In this form, the variables are called positional because the values must appear in the specified position, e.g. ?uri in the first position, ?score in the second, and so on. Any optional variables may be omitted, but processing any one of them requires specifying all the variables to the left of it. (Note: the ?selector and the ?useClustering arguments reduce the search space and so speed up the queries. ?selector is documented here. ?userClustering will use clusters within the repo if they have been created. See the description of creating clusters in a repo here.

We know from the documentation, that only two of the input variables (on the right) and one of the output variables (on the left) are required and the rest are optional. The minimal form for this predicate is:

    ?uri llm:nearestNeighbor (?text ?vectorRepoSpec)

This form is fine if we only care about the required variables. However suppose we only care about the setting the optional input ?selector and the reading optional output ?originalText. The positional syntax required a query to use an expression like

    (?uri ?score ?originalText) llm:nearestNeighbor (?text ?vectorRepoSpec ?topN ?minScore ?selector)

where all the positional arguments, up to the ones we care about, must be specified in order, even if we are willing to leave those values (?score in output and ?topN and ?minScore in input) unspecified.

The new keyword syntax allows us to write

    (?uri :originalText ?originalText) llm:nearestNeighbor (?text :selector ?selector :vectorRepoSpec ?vectorRepoSpec)

thus ignoring the output variable ?score and accepting the default values of ?topN and ?minScore. Note also that the keyword syntax permits the arguments to appear in any order.

## How Keyword Syntax Works

When Allegrograph evaluates a magic predicate within a SPARQL query, the input variables are evaluated and the output variables are bound

Whether bound or evaluated, the keyword-enabled magic predicates process variables in the same order: from left to right, treating each as a positional variable until a keyword is found. Once the left-to-right process finds a keyword, the remaining variables are expected to be given in keyword syntax. Thus, to continue with the nearestNeighbor example, in the expression

    (?uri :originalText ?originalText) llm:nearestNeighbor (?text :vectorRepoSpec ?vectorRepoSpec :selector ?selector)

the process detects ?uri and ?text as positional syntax, and ?originalText, ?vectorRepoSpec and ?selector as keyword syntax.

However the following form is invalid:

    (?uri :originalText ?originalText) llm:nearestNeighbor (?text :vectorRepoSpec ?vectorRepoSpec ?topN ?minScore ?selector)

because after the process identifies ?vectorRepoSpec as keyword syntax, it expects the remaining variables on the right be to in keyword syntax.

## A Note on Namespaces

One detail we've glossed over so far, is the way SPARQL interprets a keyword like `:key`. In order to make the token `:key` compatible with SPARQL syntax, we have to bind the empty namespace `:` to a special keyword namespace, as in the SPARQL statement

    PREFIX : <http://franz.com/ns/keyword#>

In Allegrograph, the default value of the empty namespace is (link http://franz.com/ns/keyword#), so in most cases a keyword can be abbreviated like :kw. But if the environment binds the empty namespace to something else (which is actually not uncommon) then users wanting to use the keyword syntax should bind a different prefix, such as key, as follows:

    PREFIX kw: <http://franz.com/ns/keyword#>

and then you can write the example above as:

    (?uri kw:text ?originalText) llm:nearestNeighbor (?text kw:vectorRepoSpec ?vectorRepoSpec kw:selector ?selector)

## Examples Using Keyword Syntax

Some examples may help explain the keyword syntax.

In these examples, assume we have a vector store historicalVec containing an indexed embeddings of names of famous historical figures.

Suppose we are interested in the matching original text, but not the score:

    SELECT * {
      (?uri :originalText ?originalText) llm:nearestNeighbor ("Abraham Lincoln" "historicalVec" 10 0.0)
    }

Here we set the minimum matching score, but accept the default value for the top N matches:

    SELECT * {
      (?uri :originalText ?originalText) llm:nearestNeighbor ("Abraham Lincoln" "historicalVec" :minScore 0.8)
    }

In this case we specify all the optional input variables using keyword syntax:

    SELECT * {
      (?uri ?score ?originalText) llm:nearestNeighbor ("Abraham Lincoln" "historicalVec" :topN 10 :minScore 0.0 :selector "{?id rdf:type <http://franz.com/vdb/gen/Object>}")
    }

It is even possible to place required positional arguments out-of-order using keyword syntax, as in this example where we reverse the order of the output arguments:

    SELECT * {
      (:originalText ?originalText :score ?score :uri ?uri) llm:nearestNeighbor ("Abraham Lincoln" "historicalVec")
    }

For completeness, this last example illustrates using keyword syntax with every variable:

    PREFIX llm: <http://franz.com/ns/allegrograph/8.0.0/llm/>
    SELECT * {
      (:uri ?uri :score ?score :originalText ?text :pred ?pred :type ?type)
      llm:nearestNeighbor
      (:text "Abraham Lincoln" :vectorRepoSpec "historicalVec" :topN 10 :minScore 0.8 :selector "{?id rdf:type <http://franz.com/vdb/gen/Object>.}")
    }

## LLM Predicates Accepting Keyword Syntax

The LLM magic predicates and llm:nearestNeighbor, llm:askMyDocuments, and llm:chatState. (sna:communityLeiden also accepts keywords but is not discussed in this section.)

The following tables summarizes all the keyword arguments for the three predicates.

For an explanation of the :selector argument to llm:nearestNeighbor and llm:askMyDocuments, see the Documentation for selector.

For information on creating clusters to use with the :useClustering argument, see this discussion of creating clusters.

First llm:nearestNeighbor:

Variable Role | nearestNeighbor Keyword | Optional Variable? | nearestNeighbor Variable Description
Output Variables: |  |  |
Output | `:score` | No | Match score
Output | `:uri` | Yes | ID of matching text
Output | `:originalText` | Yes | ID of matching text
Output | `:pred` | Yes | Predicate associated with embedded object
Output | `:type` | Yes | Type of subject associated with embedded object
Input Variables: |  |  |
Input | `:text` | No | Input text string
Input | `:vectorRepoSpec` | No | Vector store repo spec
Input | `:topN` | Yes | Maximum number of matches
Input | `:minScore` | Yes | Minimum score for matches
Input | `:selector` | Yes | Selects subsets of vector repo
Input | `:useClustering` | Yes | Causes a clustering created by agtool to be used, see above for more information.

Second, keyword arguments to llm:askMyDocuments:

Variable Role | askMyDocuments Keyword | Optional Variable? | askMyDocuments Variable Description
Output Variables: |  |  |
Output | `:response` | No | LLM Response text
Output | `:score` | No | Match score
Output | `:citationId` | Yes | ID of matching text
Output | `:citedText` | Yes | Matching text
Input Variables: |  |  |
Input | `:text` | No | Input text string
Input | `:vectorRepoSpec` | No | Vector store repo spec
Input | `:topN` | Yes | Maximum number of matches
Input | `:minScore` | Yes | Minimum score for matches
Input | `:selector` | Yes | Selects subsets of vector repo
Input | `:useClustering` | Yes | Causes a clustering created by agtool to be used, see above for more information.

Finally, keyword arguments to llm:chatState:

Variable Role | chatState Keyword | Optional Variable? | chatState Variable Description
Output Variables: |  |  |
Output | `:response` | No | LLM Response text
Output | `:score` | No | Match score
Output | `:citationId` | Yes | ID of matching text
Output | `:citedText` | Yes | Matching text
Output | `:citationSource` | Yes | Source vector store of match
Output | `:feed` | Yes | Recent dialog exchanges
Output | `:story` | Yes | Statement about feed
Output | `:expertiseMatchString` | Yes | Match string for Expertise repo
Output | `:expertiseMatches` | Yes | Matching Expertise embeddings and IDs
Output | `:expertiseHints` | Yes | Statement about matching expertise
Output | `:historyMatchString` | Yes | Match string for History repo
Output | `:historyMatches` | Yes | Matching history embeddings and IDs
Output | `:historyHints` | Yes | Statement about matching history
Output | `:prompt` | Yes | Prompt for LLM
Input Variables: |  |  |
Input | `:text` | No | Input text string
Input | `:expertiseRepoSpec` | No | Expertise vector repo spec
Input | `:expertiseTopN` | Yes | Maximum number of Expertise matches
Input | `:expertiseMinScore` | Yes | Minimum score for Expertise matches
Input | `:historyTopN` | Yes | Maximum number of History matches
Input | `:historyMinScore` | Yes | Minimum score for History matches
Input | `:botId` | Yes | ID of bot
Input | `:historyRepoSpec` | Yes | History vector repo spec
Input | `:selector` | Yes | Selects subsets of Expertise vector repo. Deprecated in favor of `:expertiseSelector.`
Input | `:expertiseSelector` | Yes | Selects subsets of Expertise vector repo
Input | `:historySelector` | Yes | Selects subsets of History vector repo
Input | `:useClustering` | Yes | Causes a clustering created by agtool to be used, see above for more information.