Background
CPS-1381
-
Getting issue details...
STATUS
we want to include limit/depth/pagination in CPS-Core query APIs where output size is large. it will allow user to limit query outputs.
It was discussed on 11th Nov 2022 in weekly meeting to use 'depth' parameter to limit large outputs.
Affected URLs
# | 'descendants' query parameter added in below URLs | Notes | Decision |
---|
1 | URL: http://<IP:PORT>/v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/node?xpath=/&descendants={all | none | number} | descendants is optional query parameter with default value of "all". possible values of descendants is as below : - all : to get all descendants
- none: don't include descendants
- number : to n, to query nodes till nth descendant
| - we need to support different version for this query API for backward compatibility
|
2 | URL: http://<IP:PORT>/v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes/query?cps-path=/&descendants={all | none | number} | descendants is optional query parameter with default value of "all". possible values of descendants is as below : - all : to get all descendants
- none: don't include descendants
- number : positive number 0 to n, to query nodes till nth descendant
| - we need to support different version for this query API for backward compatibility
|
Affected Methods
changes files | changes/notes |
---|
openapi.yml | /v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/node: $ref: 'cpsDataV2.yml#/nodeByDataspaceAndAnchor'
/v2/dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes/query: $ref: 'cpsQueryV2.yml#/nodesByDataspaceAndAnchorAndCpsPath' |
cpsDataV2.yml | nodeByDataspaceAndAnchor: get: description: Get a node with an option to retrieve all the children for a given anchor and dataspace tags: - cps-data summary: Get a node operationId: getNodeByDataspaceAndAnchorV2 parameters: - $ref: 'components.yml#/components/parameters/dataspaceNameInPath' - $ref: 'components.yml#/components/parameters/anchorNameInPath' - $ref: 'components.yml#/components/parameters/xpathInQuery' - $ref: 'components.yml#/components/parameters/descendantsInQuery' ... |
cpsQueryV2.yml | nodesByDataspaceAndAnchorAndCpsPath: get: description: Query data nodes for the given dataspace and anchor using CPS path tags: - cps-query summary: Query data nodes operationId: getNodesByDataspaceAndAnchorAndCpsPathV2 parameters: - $ref: 'components.yml#/components/parameters/dataspaceNameInPath' - $ref: 'components.yml#/components/parameters/anchorNameInPath' - $ref: 'components.yml#/components/parameters/cpsPathInQuery' - $ref: 'components.yml#/components/parameters/descendantsInQuery' ... |
components.yml | descendantsInQuery: name: descendants in: query description: descendants parameter to limit descendants. use "all", "none" or number required: false schema: type: string default: all example: 3 pattern: <use pattern to validate accepted values for descendants> Notes : return error descendants value if less then -1 and invalid string values. |
DataRestController.java | @Override public ResponseEntity<Object> getNodeByDataspaceAndAnchorV2(final String dataspaceName, final String anchorName, final String xpath, final String descendants) { final FetchDescendantsOption fetchDescendantsOption = getFetchDescendantOption(descendants); final DataNode dataNode = cpsDataService.getDataNode(dataspaceName, anchorName, xpath, fetchDescendantsOption); final String prefix = prefixResolver.getPrefix(dataspaceName, anchorName, xpath); return new ResponseEntity<>(DataMapUtils.toDataMapWithIdentifier(dataNode, prefix), HttpStatus.OK); } private FetchDescendantsOption getFetchDescendantOption(final String descendants) { if (null == descendants || descendants.trim().isEmpty() || "-1".equals(descendants) || "all".equals(descendants)) { return FetchDescendantsOption.INCLUDE_ALL_DESCENDANTS; } else if ("0".equals(descendants) || "none".equals(descendants)) { return FetchDescendantsOption.OMIT_DESCENDANTS; } else { final Integer depth = Integer.valueOf(descendants); return new FetchDescendantsOption(depth); } } |
QueryRestController.java | @Override public ResponseEntity<Object> getNodesByDataspaceAndAnchorAndCpsPathV2(final String dataspaceName, final String anchorName, final String cpsPath, final String descendants) { final FetchDescendantsOption fetchDescendantsOption = getFetchDescendantOption(descendants); final Collection<DataNode> dataNodes = cpsQueryService.queryDataNodes(dataspaceName, anchorName, cpsPath, fetchDescendantsOption); final List<Map<String, Object>> dataMaps = new ArrayList<>(dataNodes.size()); String prefix = null; for (final DataNode dataNode : dataNodes) { if (prefix == null) { prefix = prefixResolver.getPrefix(dataspaceName, anchorName, dataNode.getXpath()); } final Map<String, Object> dataMap = DataMapUtils.toDataMapWithIdentifier(dataNode, prefix); dataMaps.add(dataMap); } return new ResponseEntity<>(jsonObjectMapper.asJsonString(dataMaps), HttpStatus.OK); }
|
2 Comments
kieran mccarthy
HiRajesh kumar
The Jira infers a pagination mechanism but I do not see anything in the solution proposal that covers pagination as part of a depth search. Is this intentional or a missed impact or is pagination implemented? If pagination is no addressed then the Jira tile should ideally not indicate pagination is in the solution.
Thanks and Regards
Kieran
Rajesh kumar
Hi kieran mccarthy as it was mentioned above that we are using depth or descendant in query parameter to limit the large output. pagination is scope of this work but due to graph database in CPS we can only query based on depth. pagination is still matter of investigation