docs: expand docs of sparqlc:param

Author: tpluscode

README.md

@@ -79,14 +79,16 @@ const rows = await execute(params, { env, client })
 
 ### Reference parameters with `sparqlc:param`
 
-You can declare and consume query parameters inside `.rq` files using the RDF property/function identified by `https://sparqlc.described.at/param` (IRI). Use a prefix for convenience:
+You can declare and consume query parameters inside `.rq` files using the SPARQL function identified by `https://sparqlc.described.at/param` (IRI). Use a prefix for convenience:
 
 ```sparql
 PREFIX sparqlc: <https://sparqlc.described.at/>
 ```
 
-- (Recommended) Function style: `sparqlc:param("name")`
+- Parameter function: `sparqlc:param("name")` or `sparqlc:param(prefix:name)`
   - Can be easily inlined in `BIND`, `FILTER`, or anywhere an expression is allowed.
+  - String literal keys: `BIND(sparqlc:param("minAge") AS ?minAge)`
+  - NamedNode / IRI keys: `BIND(sparqlc:param(schema:mainEntity) AS ?entity)`
   - Example:
     ```sparql
     PREFIX foaf: <http://xmlns.com/foaf/0.1/>
@@ -97,37 +99,22 @@ PREFIX sparqlc: <https://sparqlc.described.at/>
       FILTER (?age >= sparqlc:param("minAge"))
     }
     ```
-
-- Pattern style: `?variable sparqlc:param "name" .`
-  - This binds the value of the parameter `"name"` to the SPARQL variable `?variable`.
-  - Example:
-    ```sparql
-    PREFIX foaf: <http://xmlns.com/foaf/0.1/>
-    PREFIX sparqlc: <https://sparqlc.described.at/>
-    
-    SELECT ?person WHERE {
-      ?name sparqlc:param "person" .  
-    
-      ?person a foaf:Person ;
-              foaf:name ?name .
-    }
-    ```
     Runtime call:
     ```ts
     import env from '@zazuko/env'
-    const rows = await execute({ person: env.namedNode('http://example.com/alice') }, { env, client })
+    const rows = await execute({ minAge: env.literal('18', env.ns.xsd.integer) }, { env, client })
     ```
 
 Passing parameters at runtime
 - You may pass parameters as:
   - `Record<string, Term>`: `{ person: env.namedNode('...'), minAge: env.literal('18', xsdInteger) }`
   - `URLSearchParams`: `new URLSearchParams([["person", "http://example.com/alice"], ["minAge", "18"]])` (simple string values)
-  - `Map<Term, Term | Term[]>` for full control
+  - `Map<Term, Term | Term[]>` to use NamedNode parameter names
 - Values are RDFJS `Term`s. For typed literals, construct them via your RDF environment (e.g., `@zazuko/env`).
 
 Notes
 - The parameter IRI is exactly `https://sparqlc.described.at/param`.
-- Use `PREFIX sparqlc: <https://sparqlc.described.at/>` so `sparqlc:param` expands to that IRI in both triple and function forms.
+- Use `PREFIX sparqlc: <https://sparqlc.described.at/>` so `sparqlc:param` expands to that IRI.
 - Arrays (`Term[]`) are supported by the runtime API for positions that accept multiple terms (e.g., via custom processors). Your usage may vary depending on processors you apply.
 
 ### CLI usage

packages/sparqlc/README.md

@@ -62,19 +62,100 @@ const { default: insertData } = await import('./queries/insert-data.ru')
 await insertData({ env, client })
 ```
 
-#### Binding parameters
+#### Binding parameters with `sparqlc:param`
 
-Queries can declare variables to be bound at execution time. Provide a map of RDF terms as the first argument. Keys may be full variable names or well‑known IRIs (helpful with `@zazuko/env`).
+Queries can declare variables and placeholders to be bound at execution time using the `sparqlc:param` SPARQL function.
 
-```ts
-const params = env.termMap([
-  [env.ns.schema.mainEntity, env.namedNode('http://example.org/fruits/Banana')],
-])
+##### Declaring parameters in SPARQL queries
+
+Declare the `sparqlc:` prefix:
 
-const { default: construct } = await import('./queries/construct-named-node-param.rq')
-const dataset = await construct(params, { env, client })
+```sparql
+PREFIX sparqlc: <https://sparqlc.described.at/>
 ```
 
+You can use `sparqlc:param(...)` in `BIND(...)` expressions, `FILTER(...)` expressions, or anywhere SPARQL expressions are valid:
+
+- **String literal parameter keys**: Identify parameters by string name.
+  ```sparql
+  # queries/select-by-type.rq
+  PREFIX sparqlc: <https://sparqlc.described.at/>
+  PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+
+  SELECT ?res ?label WHERE {
+    BIND(sparqlc:param("type") AS ?type)
+
+    ?res a ?type ;
+         rdfs:label ?label .
+  }
+  ```
+
+- **NamedNode / IRI parameter keys**: Identify parameters using full IRIs or prefixed names (such as schema.org terms).
+  ```sparql
+  # queries/construct-named-node-param.rq
+  PREFIX sparqlc: <https://sparqlc.described.at/>
+  PREFIX schema: <http://schema.org/>
+  PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+
+  CONSTRUCT {
+    ?fruit rdfs:label ?label .
+  } WHERE {
+    BIND(IRI(sparqlc:param(schema:mainEntity)) AS ?fruit)
+
+    ?fruit rdfs:label ?label .
+  }
+  ```
+
+- **In `FILTER` expressions**:
+  ```sparql
+  PREFIX sparqlc: <https://sparqlc.described.at/>
+
+  SELECT ?s ?val WHERE {
+    ?s ?p ?val .
+    FILTER(?val = sparqlc:param("expected"))
+  }
+  ```
+
+- **Scoped evaluation**: `sparqlc:param` can be used inside `GRAPH`, `OPTIONAL`, `SERVICE`, `MINUS`, unions, sub-selects, and update operations (`INSERT`, `DELETE`). Parameter values are injected into the query via appropriately scoped `VALUES` clauses according to SPARQL bottom-up evaluation semantics.
+
+##### Passing parameters at execution time
+
+Pass parameter values as the first argument(s) to the imported query function. `sparqlc` supports several formats:
+
+- **Plain object dictionary (`Record<string, Term>`)**:
+  ```ts
+  import env from '@zazuko/env'
+  const { default: selectByType } = await import('./queries/select-by-type.rq')
+
+  const rows = await selectByType(
+    { type: env.namedNode('http://example.org/Fruit') },
+    { env, client }
+  )
+  ```
+
+- **RDF/JS `TermMap` / `Map<Term, Term | Term[]>`**: Useful for NamedNode parameter keys and full control over RDF terms.
+  ```ts
+  import env from '@zazuko/env'
+  const { default: construct } = await import('./queries/construct-named-node-param.rq')
+
+  const params = env.termMap([
+    [env.ns.schema.mainEntity, env.namedNode('http://example.org/fruits/Banana')],
+  ])
+
+  const dataset = await construct(params, { env, client })
+  ```
+
+- **`URLSearchParams`**: Useful for query strings.
+  ```ts
+  const params = new URLSearchParams([['type', 'http://example.org/Fruit']])
+  const rows = await selectByType(params, { env, client })
+  ```
+
+- **Multiple parameter sources**: Multiple parameter maps or objects can be provided in sequence before the options argument.
+  ```ts
+  const rows = await selectQuery(params1, params2, { env, client })
+  ```
+
 #### Runtime query options
 
 Queries can be modified at execution time using runtime options: