@cubicweb/rql-generator
Version:
Helpers to build RQL queries
233 lines • 11.5 kB
TypeScript
import { EntitySchema, RQLQueryCellRef, RelationDefinitionSchema } from "@cubicweb/client";
import { AttributeValue, EntityData } from "./types.js";
import { RQLQueryRestrictions } from "./RqlQueryRestrictions.js";
/**
* Converts an attribute type to a RQL variable name.
* All RQL queries generated in this package use this function to create the variable names.
* Use this to build your own RQL requests or edit ones generated with this package.
*
* @param attribute The attribute type to convert
* @returns A RQL variable name
*
* @category RQL Generation
*/
export declare function attributeToVariable(attribute: string): string;
/**
* Converts a subject relation type to a RQL variable name.
* All RQL queries generated in this package use this function to create the variable names.
* Use this to build your own RQL requests or edit ones generated with this package.
*
* @param relation The subject relation type to convert
* @returns A RQL variable name
*
* @category RQL Generation
*/
export declare function subjectRelationToVariable(relation: string): string;
/**
* Converts an object relation type to a RQL variable name.
* All RQL queries generated in this package use this function to create the variable names.
* Use this to build your own RQL requests or edit ones generated with this package.
*
* @param relation The object relation type to convert
* @returns A RQL variable name
*
* @category RQL Generation
*/
export declare function objectRelationToVariable(relation: string): string;
/**
* Converts a relation or attribute type to a RQL variable name.
* All RQL queries generated in this package use this function to create the variable names.
* Use this to build your own RQL requests or edit ones generated with this package.
*
* @remarks Object relations must have the reverse prefix. See [@cubicweb/client:getReverseRelationType](https://cubicweb.pages.logilab.fr/cubicwebjs/client/functions/getReverseRelationType.html)
*
* @param relationType The relation type to get the variable name from
* @param attributes The list of attributes to search the relation type in
* @param subjectRelations The list of subject relations to search the relation type in
* @param objectRelations The list of object relations to search the relation type in
* @returns The name of the relation type depending if it represents an attribute, subject or object relation.
* @throws If the relation type cannot be found in the given relations.
*
* @category RQL Generation
*/
export declare function getRelationVariable(relationType: string, attributes: Array<RelationDefinitionSchema>, subjectRelations: Array<RelationDefinitionSchema>, objectRelations: Array<RelationDefinitionSchema>): string;
/**
* Resolves the list of attributes, subject and object relations from the given array of relation types.
* Relation types not existing in the given entity type schema will be ignored.
*
* If no relation type array is given, then all attributes and subject relations are returned.
*
* @remarks ⚠️ Even relations internal to cubicweb such as `created_by` are returned in this case.
* Use `RELATIONS_AND_ATTRIBUTES_METAMODEL` constant to filter those out.
*
* @param entitySchema The entity type schema
* @param relationsToResolve The list of relation types to resolve. Object relations must have the reverse prefix. See [@cubicweb/client:getReverseRelationType](https://cubicweb.pages.logilab.fr/cubicwebjs/client/functions/getReverseRelationType.html)
* @returns An object containing the attributes, subject and object relations lists
*
* @category RQL Generation
*/
export declare function getRelationsSchemata(entitySchema: EntitySchema, relationsToResolve?: Array<string>): {
attributes: RelationDefinitionSchema<import("@cubicweb/client").EntityRawSchemaArray, import("@cubicweb/client").RelationDefinitionRawSchemaArray<import("@cubicweb/client").EntityRawSchemaArray>, Readonly<{
type: string;
description: string;
cardinality: "**" | "*1" | "*?" | "*+" | "1*" | "11" | "1?" | "1+" | "?*" | "?1" | "??" | "?+" | "+*" | "+1" | "+?" | "++";
subject: string;
} & ((import("@cubicweb/client").BuildObj & {
final: true;
constraints: import("@cubicweb/client").AttributeConstraint[];
options: import("@cubicweb/client").AttributeOptions;
}) | {
object: string;
final: false;
constraints: import("@cubicweb/client").RelationConstraint[];
options: import("@cubicweb/client").RelationOptions;
})>>[];
subjectRelations: RelationDefinitionSchema<import("@cubicweb/client").EntityRawSchemaArray, import("@cubicweb/client").RelationDefinitionRawSchemaArray<import("@cubicweb/client").EntityRawSchemaArray>, Readonly<{
type: string;
description: string;
cardinality: "**" | "*1" | "*?" | "*+" | "1*" | "11" | "1?" | "1+" | "?*" | "?1" | "??" | "?+" | "+*" | "+1" | "+?" | "++";
subject: string;
} & ((import("@cubicweb/client").BuildObj & {
final: true;
constraints: import("@cubicweb/client").AttributeConstraint[];
options: import("@cubicweb/client").AttributeOptions;
}) | {
object: string;
final: false;
constraints: import("@cubicweb/client").RelationConstraint[];
options: import("@cubicweb/client").RelationOptions;
})>>[];
objectRelations: RelationDefinitionSchema<import("@cubicweb/client").EntityRawSchemaArray, import("@cubicweb/client").RelationDefinitionRawSchemaArray<import("@cubicweb/client").EntityRawSchemaArray>, Readonly<{
type: string;
description: string;
cardinality: "**" | "*1" | "*?" | "*+" | "1*" | "11" | "1?" | "1+" | "?*" | "?1" | "??" | "?+" | "+*" | "+1" | "+?" | "++";
subject: string;
} & ((import("@cubicweb/client").BuildObj & {
final: true;
constraints: import("@cubicweb/client").AttributeConstraint[];
options: import("@cubicweb/client").AttributeOptions;
}) | {
object: string;
final: false;
constraints: import("@cubicweb/client").RelationConstraint[];
options: import("@cubicweb/client").RelationOptions;
})>>[];
};
/**
* Generates the selection clause of a RQL query for the given attributes and relations.
*
* @remarks The variable `X` will always be part of the selection clause.
* If you do not supply any relation, `X` will be returned.
* Relations with cardinality `+` and `*` will be surrounded with [`GROUP_CONCAT`](https://cubicweb.readthedocs.io/en/stable/book/annexes/rql/language.html?highlight=GROUP_CONCAT#aggregate-functions).
*
* @example
* When given the title and content attributes
* ```
* Selection clause
* |---------------------------|
* | |
* Any X, ATTR_TITLE, ATTR_CONTENT WHERE X eid 1, X title ATTR_TITLE, X content ATTR_CONTENT
* ```
*
* @param attributes The list of attributes
* @param subjectRelations The list of subject relations
* @param objectRelations The list of object relations
* @returns A string representing a selection clause in a RQL query
*
* @category RQL Generation
*/
export declare function getSelectionClause(attributes: Array<RelationDefinitionSchema>, subjectRelations: Array<RelationDefinitionSchema>, objectRelations: Array<RelationDefinitionSchema>): string;
/**
* Generates the filter clause of a RQL query for the given data.
*
* @remarks Does not handle object relations
*
* * @example
* When given the title
* ```
* Filter clause
* |-----------------|
* | |
* Any X, ATTR_CONTENT WHERE X content ATTR_CONTENT, X title %(title)s
* ```
*
* @param data Object with attributes/relations as keys and their value as values
* @param entitySchema The schema of the entity to filter
* @returns A RQL query to filter the entity using the data
*/
export declare function getFilterRestrictionClause(data: EntityData, entitySchema: EntitySchema): RQLQueryRestrictions;
/**
* Generates the restriction clause of a RQL query for the given attributes and relations.
*
* @remarks The restriction on `X` never be set.
* If you do not supply any relation, the returned string will be empty.
*
* @example
* When given the title and content attributes
* ```
* Any X, ATTR_TITLE, ATTR_CONTENT
* Restriction clause
* |------------------------------------------|
* | |
* WHERE X eid 1, X title ATTR_TITLE, X content ATTR_CONTENT
* ```
* @param attributes The list of attributes
* @param subjectRelations The list of subject relations
* @param objectRelations The list of object relations
* @returns A string representing a restriction clause in a RQL query
*
* @category RQL Generation
*/
export declare function getRestrictionsClause(attributes: Array<RelationDefinitionSchema>, subjectRelations: Array<RelationDefinitionSchema>, objectRelations: Array<RelationDefinitionSchema>): string;
/**
* Generates the GROUP BY clause of a RQL query for the given attributes and relations.
* It will only consider relations of cardinality `1` and `?`.
* Relations of cardinality `+` or `*` will be ignored.
*
* @remarks The group by on `X` will always be set.
* If you do not supply any relation, `GROUPBY X` will be returned.
*
* @example
* When given the title and content attributes
* ```
* Group by clause
* |-----------------------------------|
* | |
* Any X, ATTR_TITLE, ATTR_CONTENT GROUPBY X, ATTR_TITLE, ATTR_CONTENT
* WHERE X is BlogEntry, X title ATTR_TITLE, X content ATTR_CONTENT
* ```
* @param attributes The list of attributes
* @param subjectRelations The list of subject relations
* @param objectRelations The list of object relations
* @returns A string representing a GROUP BY clause in a RQL query
*
* @category RQL Generation
*/
export declare function getGroupByClause(attributes: Array<RelationDefinitionSchema>, subjectRelations: Array<RelationDefinitionSchema>, objectRelations: Array<RelationDefinitionSchema>): string;
/**
* Generates the RQL clause to update attributes for a given entity.
*
* @remarks Unknown attributes used as keys in the `attributesData` param will be ignored.
* If no valid attribute is supplied in the data, the returned clause will be empty.
*
* @example
* When given the title and content attributes
* ```
* Attributes update clause
* |----------------------------------------|
* | |
* SET X title %(title)s, X content %(content)s WHERE X is BlogEntry, X eid 1
* ```
*
* @param entitySchema The entity schema
* @param attributesData An object with each attribute type as key and their values as value
* @returns An object containing the RQL clause and the parameters associated
* @throws If an attribute does not exist in the schema
*
* @category RQL Generation
*/
export declare function getAttributesUpdateClause(entitySchema: EntitySchema, attributesData: Record<string, AttributeValue>): {
attributesUpdates: string;
params: Record<string, RQLQueryCellRef | AttributeValue>;
};
//# sourceMappingURL=rql.d.ts.map