cmem_client.models.query_catalog

Models for query catalog operations.

This module provides data models for query catalog operations including query explanation, execution, status tracking, and catalog management.

The queries stored in the catalog are the items of client.queries, keyed by their URL. A query carries its own text, so it knows its type and its {{placeholder}} parameters without asking the server, and the same model is used for a query which was never in the catalog at all, read from a file or built from a string.

Classes:

• LogicalPlan – Logical plan explanation for a SPARQL query.
• Query – A SPARQL query with metadata and placeholder support.
• QueryOrigin – Origin of a query.
• QueryStatus – Status information for a running or completed query.
• QueryType – SPARQL query type enumeration.

LogicalPlan

Bases: Model

Logical plan explanation for a SPARQL query.

Represents the query execution plan returned by the query catalog API, which provides information about query optimization, execution order, and estimated complexity.

Attributes:

• plan (str) – The formatted query execution plan showing optimization groups, collection sizes, complexity estimates, and iteration counts.

model_config

model_config = ConfigDict(extra='allow', populate_by_name=True)

plan

plan: str

The formatted query execution plan as a string.

Query

Bases: Model, ReadRepositoryItem

A SPARQL query with metadata and placeholder support.

Represents a SPARQL query with support for parameterization using mustache-like syntax ({{placeholder}}). Includes query type detection, placeholder management, and execution configuration.

Attributes:

• text (str) – The SPARQL query text, potentially containing placeholders.
• url (str) – URI identifying this query in the query catalog (auto-generated if not provided).
• label (str | None) – Optional human-readable label for the query.
• query_type (QueryType) – The detected or specified query type (SELECT, UPDATE, etc.).
• description (str | None) – Optional description of the query’s purpose.
• origin (QueryOrigin) – Where the query came from (remote, file, text).
• short_url (str | None) – Shortened URL with default namespace prefix (e.g., :uuid).

Functions:

• detect_query_type – Detect the query type by parsing the query text.
• fill_placeholders – Replace placeholders with provided values.
• generate_url_if_missing – Generate a URL if none provided.
• get_default_accept_header – Get the default Accept header for this query type.
• get_editor_url – Get the Corporate Memory query editor URL for this query.
• get_id – Get the query URL as its identifier.
• get_placeholder_keys – Get all placeholder keys from the query text.

DEFAULT_NS

DEFAULT_NS: str = 'https://ns.eccenca.com/data/queries/'

description

description: str | None = None

detect_query_type

detect_query_type(text=None)

Detect the query type by parsing the query text.

Uses rdflib’s SPARQL parser to determine if this is a SELECT, ASK, DESCRIBE, CONSTRUCT, or UPDATE query.

Parameters:

• text (str | None) – Optional query text to parse. If None, uses self.text.

Returns:

• QueryType – Detected QueryType, or QueryType.UNKNOWN if detection fails.

Examples:

>>> query = Query(text="SELECT * { ?s ?p ?o }")
>>> query.detect_query_type()
<QueryType.SELECT: 'SELECT'>

fill_placeholders

fill_placeholders(placeholders)

Replace placeholders with provided values.

Parameters:

• placeholders (dict[str, str]) – Dictionary mapping placeholder keys to values.

Returns:

• str – Query text with all placeholders replaced.

Raises:

• ValueError – If not all placeholders are filled.

Examples:

>>> query = Query(text="SELECT * { ?s ?p {{value}} }")
>>> query.fill_placeholders({"value": '"test"'})
'SELECT * { ?s ?p "test" }'

generate_url_if_missing

generate_url_if_missing(v)

Generate a URL if none provided.

get_default_accept_header

get_default_accept_header()

Get the default Accept header for this query type.

Returns appropriate MIME type based on query type, biased towards formats suitable for command-line display.

Returns:

• str – Accept header string (e.g., “text/csv”, “text/turtle”).

Examples:

>>> query = Query(text="SELECT * { ?s ?p ?o }", query_type=QueryType.SELECT)
>>> query.get_default_accept_header()
'text/csv'

get_editor_url

get_editor_url(base_url, graph=None)

Get the Corporate Memory query editor URL for this query.

Generates a URL to open the query in Corporate Memory’s web-based SPARQL query editor.

Parameters:

• base_url (str) – Base URL of Corporate Memory instance (required).
• graph (str | None) – Catalog graph URI for remote queries (default: DEFAULT_NS).

Returns:

• str – URL string to open query in the web editor.

Examples:

>>> query = Query(text="SELECT * { ?s ?p ?o }", origin=QueryOrigin.TEXT)
>>> url = query.get_editor_url(base_url="https://cmem.example.com")
>>> "queryString" in url
True

get_id

get_id()

Get the query URL as its identifier.

Returns:

• str – The query URL (IRI) that uniquely identifies this query in the catalog.

get_placeholder_keys

get_placeholder_keys(text=None)

Get all placeholder keys from the query text.

Placeholders use mustache-like syntax: {{placeholder_name}}

Parameters:

• text (str | None) – Optional text to scan. If None, uses self.text.

Returns:

• set[str] – Set of placeholder key names found in the text.

Examples:

>>> query = Query(text="SELECT * { ?s ?p {{value}} }")
>>> query.get_placeholder_keys()
{'value'}

label

label: str | None = None

model_config

model_config = ConfigDict(extra='allow', populate_by_name=True)

origin

origin: QueryOrigin = QueryOrigin.UNKNOWN

query_type

query_type: QueryType = QueryType.UNKNOWN

short_url

short_url: str | None = None

text

text: str

url

url: str = ''

QueryOrigin

Bases: StrEnum

Origin of a query.

Indicates where the query came from for tracking and editor URL generation.

Attributes:

• FILE –
• REMOTE –
• TEXT –
• UNKNOWN –

FILE

FILE = 'file'

REMOTE

REMOTE = 'remote'

TEXT

TEXT = 'text'

UNKNOWN

UNKNOWN = 'unknown'

QueryStatus

Bases: Model

Status information for a running or completed query.

Represents the execution status of a query including timing information, user context, and trace identifiers for debugging.

The API returns camelCase field names which are automatically converted to snake_case Python attributes using Pydantic field aliases.

Attributes:

• id (str | None) – Unique identifier for this query execution.
• query_string (str | None) – The query text that was executed.
• graph (str | None) – Graph URI the query was executed against.
• user (str | None) – User who executed the query.
• trace_id (str | None) – Trace identifier for debugging.
• start_time (int | None) – When the query started execution (milliseconds).
• execution_time (int | None) – How long the query took to execute (milliseconds).
• affected_graphs (list[str] | None) – Graph URIs an update query wrote to. Empty for a read query.
• status (str | None) – Current status (e.g., “running”, “completed”).

affected_graphs

affected_graphs: list[str] | None = Field(default=None, alias='affectedGraphs')

execution_time

execution_time: int | None = Field(default=None, alias='executionTime')

graph

graph: str | None = None

id

id: str | None = None

model_config

model_config = ConfigDict(extra='allow', populate_by_name=True)

query_string

query_string: str | None = Field(default=None, alias='queryString')

start_time

start_time: int | None = Field(default=None, alias='startTime')

status

status: str | None = None

trace_id

trace_id: str | None = Field(default=None, alias='traceId')

user

user: str | None = None

QueryType

Bases: StrEnum

SPARQL query type enumeration.

Categorizes queries into read operations (SELECT, ASK, DESCRIBE, CONSTRUCT) and update operations (UPDATE, DELETE, INSERT, etc.).

Functions:

• is_read_query – Check if this is a read query type.
• is_update_query – Check if this is an update query type.
• read_types – Get all read query types (SELECT, ASK, DESCRIBE, CONSTRUCT).
• update_types – Get all update query types.

Attributes:

• ADD –
• ASK –
• CLEAR –
• CONSTRUCT –
• COPY –
• CREATE –
• DELETE –
• DESCRIBE –
• DROP –
• FAULTY –
• INSERT –
• LOAD –
• MOVE –
• SELECT –
• UNKNOWN –
• UPDATE –

ADD

ADD = 'ADD'

ASK

ASK = 'ASK'

CLEAR

CLEAR = 'CLEAR'

CONSTRUCT

CONSTRUCT = 'CONSTRUCT'

COPY

COPY = 'COPY'

CREATE

CREATE = 'CREATE'

DELETE

DELETE = 'DELETE'

DESCRIBE

DESCRIBE = 'DESCRIBE'

DROP

DROP = 'DROP'

FAULTY

FAULTY = 'FAULTY'

INSERT

INSERT = 'INSERT'

LOAD

LOAD = 'LOAD'

MOVE

MOVE = 'MOVE'

SELECT

SELECT = 'SELECT'

UNKNOWN

UNKNOWN = 'UNKNOWN'

UPDATE

UPDATE = 'UPDATE'

is_read_query

is_read_query()

Check if this is a read query type.

is_update_query

is_update_query()

Check if this is an update query type.

read_types

read_types()

Get all read query types (SELECT, ASK, DESCRIBE, CONSTRUCT).

update_types

update_types()

Get all update query types.

Comments