Methods
The following methods are defined on theQueryService
query
Query for multiple records, with a filter, paging and sorting.
Arguments
query: Query<DTO>- The query to filter, page, and sort results.
Returns
An array of DTOsfindById
Find a record by its id.
Arguments
id: string | number- The id of the record to find
Returns
The DTO or undefinedgetById
- get a record by its id or return a rejected promise with a NotFound error.
Arguments
id: string | number- The id of the record to find
Returns
The DTO or a NotFoundException.createMany
Create multiple records.
Arguments
items: DeepPartial<DTO>[]- An array of partial DTOs to persist
Returns
The saved DTOs.createOne
Create a single DTO.
Arguments
item: DeepPartial<DTO>- A partial of the DTO to persist
Returns
The saved DTOupdateMany
Update multiple records based on a filter.
Arguments
update: DeepPartial<DTO>- The update to applyfilter: Filter<DTO>- AFilterused to find the records to update
Returns
An object with theupdatedCount
UpdatedCount may be 0 if the database does not return the number of rows updated.
updateOne
Update a single record.
Arguments
id: string | number- The id of the record to updateupdate: DeepPartial<DTO>- The update to apply
Returns
The updated DTOdeleteMany
Delete multiple records.
Arguments
filter: Filter<DTO>- The filter to find the records to delete.
Returns
An object with adeletedCount field.
deletedCount may be 0 if the database does not return the number of rows deleted.deleteOne
Delete a single record.
Arguments
id: number | string
Returns
Promise<DTO>
aggregate
Performs an aggregate query, supported aggregate functions are groupBy, count, sum, avg, min, and max
Arguments
filter: Filter<DTO>- Additional filter to applyaggregate: AggregateQuery<DTO>- The aggregate query
AggregateQuery
Returns
An array of aggregate responses. ExampleAggregateResponse
count
Count the number of records that match the filter
Arguments
filter: Filter<DTO>- The filter a count records by
Returns
A count of records that match thefilter
queryRelations
Query for relations
Arguments
RelationClass: Class<Relation>- TheClasstype of the relationrelationName: string- The name of the relationdto: DTO | DTO[]- The dto(s) to find the relations for.query: Query<Relation>- Additional query to use when querying for relations.
Returns
If querying for relations for a singleDTO an array of relations will be returned. If querying for relations for multiple DTOs a map where the key is the DTO and the value is the relations for the DTO.
aggregateRelations
Performs an aggregate query for the relations of a DTO.
Arguments
RelationClass: Class<Relation>- TheClasstype of the relationrelationName: string- The name of the relationdto: DTO | DTO[]- The dto(s) to aggregate the relations for.filter: Filter<Relation>- Afilterto apply when aggregating relationsaggregate: AggregateQuery<Relation>- TheaggregateQueryfor the relations
Returns
If aggregating relations for a singleDTO an AggregateResponse for the dtos relations will be returned If aggregating relations for multiple DTOs a map where the key is the DTO and the value is the AggregateResponse for the dtos relations.
countRelations
Counts the number of relations.
Arguments
RelationClass: Class<Relation>- TheClasstype of the relationrelationName: string- The name of the relationdto: DTO | DTO[]- The dto(s) to count the relations for.filter: Filter<Relation>- Afilterto apply when counting relations
Returns
If counting relations for a singleDTO the relation count will be returned If counting relations for multiple DTOs a map where the key is the DTO and the value is relation count for the dtos relations.
findRelation
Find a single relation for the DTO(s).
Arguments
RelationClass: Class<Relation>- TheClasstype of the relationrelationName: string- The name of the relationdto: DTO | DTO[]- The dto(s) to find the relation for.opts?: FindRelationOptions<Relation>- Additional options to find a relation by.
Returns
If finding a relation for a singleDTO the relation or undefineding returned If finding a relation for multiple DTOs a map where the key is the DTO and the value is the relation or undefined.
addRelations
Adds relations to a DTO
Arguments
relationName: string- The name of the relationid: string | number- The id of the DTO to add the relations torelationIds: (string | number)[]- The ids of the relations to addopts?: ModifyRelationOptions<DTO, Relation>- Additional options apply when adding relations
Returns
The DTO the relations were added to.setRelations
Sets relations on a DTO
Arguments
relationName: string- The name of the relationid: string | number- The id of the DTO to add the relations torelationIds: (string | number)[]- The ids of the relations to set. If the relationIds is empty the all relations will be removed.opts?: ModifyRelationOptions<DTO, Relation>- Additional options apply when adding relations
Returns
The DTO the relations were added to.setRelation
Set a relation on a DTO
Arguments
relationName: string- The name of the relationid: string | number- The id of the DTO to add the relations torelationId: string | number- The id of the relation to set on the DTOopts?: ModifyRelationOptions<DTO, Relation>- Additional options apply when setting the relation
Returns
The DTO the relation was set on.removeRelations
Removes multiple relations from a DTO
Arguments
relationName: string- The name of the relationid: string | number- The id of the DTO to remove the relations from.relationIds: (string | number)[]- The ids of the relations to removeopts?: ModifyRelationOptions<DTO, Relation>- Additional options to apply when removing relations
Returns
The DTO the relations were removed fromremoveRelation
Remove a relation from a DTO
Arguments
relationName: string- The name of the relationid: string | number- The id of the DTO to remove the relation from.relationId: string | number- The id of the relation to removeopts?: ModifyRelationOptions<DTO, Relation>- Additional options to apply when removing the relation.
Returns
The DTO the relation was removed from.Service Helpers
You can create your own service to use with theCRUDResolver as long as it implements the QueryService interface.
There are a number of persistence QueryServices that are provided out of the box.
In addition to the persistence QueryServices @ptc-org/nestjs-query-core provides a few helper services that can be used for more complex use cases.
When designing the base services we have chosen composition over inheritance. This approach lends itself well to modeling complex services without repeating yourself.
RelationQueryService
The RelationQueryService was originally designed for federation, but has proven itself useful in representing virtual relations. A virtual relation(s) is anything that can be queried through a query service. To create additional relations through a RelationQueryService you need to provide the following- A
QueryServicethat can be used to fetch the relation - A
queryfunction that accepts the parent DTO to fetch the relation for and returns aQueryto fetch the relations.
Relations defined using the
RelationQueryService are readonly!- First check if the relation is a virtual relation, if
trueit will invoke thequeryoption to generate a query that will be passed to thequeryServiceto fetch the relations. - If the relation is not a
virtualrelation it will proxy to the original query service to query for the relation.
TodoItem query service and add a completedSubTasks relation.
todo-item/todo-item.service.ts
relation is defined in the query service we can add it to our DTO to expose it in our schema.
todo-item/todo-item.dto.ts
SubTask query service from the SubTaskModule so we can resolve it in the TodoItemService.
sub-task/sub-task.module.ts
SubTaskModule into the TodoItemModule so the SubTask query service can be injected into the TodoItemService.
todo-item/todo-item.module.ts
completedSubTasks relation is now available in your graphql schema.
ProxyQueryService
TheProxyQueryService is a query service that delegates to another query service. The ProxyQueryService can be used when you want to override certain methods of a query service without extending it.
This class is used internally by the RelationQueryService to override the relation methods for a QueryService
Lets use the ProxyQueryService to create a generic query service that will time and log a message everytime a create, update, or delete method is called.
To start lets define a MutationLoggerQueryService.
utilities/mutation-logger-query.service.ts
TodoItemQueryService
todo-item/todo-item.service.ts
NoOpQueryService
The no-op query service is one that will throw aNotImplementedException for every method.
This is commonly used during testing when you want to mock out a service.
You can also use the NoOpQueryService as a base a new query service that only supports a subset of operations.
In this example we’ll create a simple query service that stores elements in an array but does not support relations or aggregations.