Sensible and performant way to descendants of an item the REST API

Steve Jorgensen
Steve Jorgensen Member Posts: 8
edited March 13 in Peer-to-Peer Support Forum

I have scoured the REST API documentation, and I don't see that there is any straightforward way to query for descendants or even just direct children of an item.

The only technique that I have been able to figure out to get those is to first retrieve ALL of the items in a project, then determine their containership hierarchies via location.parent references, and then use that to identify which of the items are descendants of the starting item.

Is there something I am missing, or is that a capability that can be added to a future release?



------------------------------
Steve Jorgensen
Cliosoft
OR
------------------------------

Comments

  • Colin Marquardt
    Colin Marquardt Member, Data Exchange Posts: 15
    edited February 2023

    There is <a href="https://rest.jamasoftware.com/#operation_getChildItems">GET /items/{id}/children</a> as well as /downstreamrelated and /downstreamrelationships which should be helpful.



    ------------------------------
    Colin Marquardt
    Bosch Sensortec GmbH
    ------------------------------
    -------------------------------------------
    Original Message:
    Sent: 02-08-2023 14:20
    From: Steve Jorgensen
    Subject: Sensible and performant way to descendants of an item the REST API

    I have scoured the REST API documentation, and I don't see that there is any straightforward way to query for descendants or even just direct children of an item.

    The only technique that I have been able to figure out to get those is to first retrieve ALL of the items in a project, then determine their containership hierarchies via location.parent references, and then use identify which of the items are descendants of the starting item.

    Is there something I am missing, or is that a capability that can be added to a future release?



    ------------------------------
    Steve Jorgensen
    Cliosoft
    OR
    ------------------------------

  • Nick McHale
    Nick McHale Jama Staff, Data Exchange Posts: 1
    edited February 2023

    Hi Steve,

    The most efficient way to fetch an entire subtree of items is to use the GET /abstractitems endpoint.  You can apply two filters to achieve the desired result.

    1. Use the project parameter to filter items from the current project.
    2. Use the contains parameter to filter items that match your parent items sequence number using Lucene search (https://dev.jamasoftware.com/cookbook/#abstract-lucene-parameters)
      For example, to fetch all descendants of the item with sequence number 2.4 you would enter the following into the contains field: "sequence: 2.4.*"

    I hope this helps.



    ------------------------------
    Nick McHale
    Team Lead - Software Engineer
    Jama Software
    Portland OR
    ------------------------------
    -------------------------------------------
    Original Message:
    Sent: 02-08-2023 14:20
    From: Steve Jorgensen
    Subject: Sensible and performant way to descendants of an item the REST API

    I have scoured the REST API documentation, and I don't see that there is any straightforward way to query for descendants or even just direct children of an item.

    The only technique that I have been able to figure out to get those is to first retrieve ALL of the items in a project, then determine their containership hierarchies via location.parent references, and then use identify which of the items are descendants of the starting item.

    Is there something I am missing, or is that a capability that can be added to a future release?



    ------------------------------
    Steve Jorgensen
    Cliosoft
    OR
    ------------------------------

    Nick McHale
    Team Lead - Software Engineer
    Jama Software
    Portland Oregon
  • Steve Jorgensen
    Steve Jorgensen Member Posts: 8
    edited February 2023

    How did I manage to miss that? Thanks.

    ------------------------------
    Steve Jorgensen
    Cliosoft
    OR
    ------------------------------
    -------------------------------------------
    Original Message:
    Sent: 02-09-2023 00:24
    From: Colin Marquardt
    Subject: Sensible and performant way to descendants of an item the REST API

    There is <a href="https://rest.jamasoftware.com/#operation_getChildItems">GET /items/{id}/children</a> as well as /downstreamrelated and /downstreamrelationships which should be helpful.



    ------------------------------
    Colin Marquardt
    Bosch Sensortec GmbH
    ------------------------------

    Original Message:
    Sent: 02-08-2023 14:20
    From: Steve Jorgensen
    Subject: Sensible and performant way to descendants of an item the REST API

    I have scoured the REST API documentation, and I don't see that there is any straightforward way to query for descendants or even just direct children of an item.

    The only technique that I have been able to figure out to get those is to first retrieve ALL of the items in a project, then determine their containership hierarchies via location.parent references, and then use identify which of the items are descendants of the starting item.

    Is there something I am missing, or is that a capability that can be added to a future release?



    ------------------------------
    Steve Jorgensen
    Cliosoft
    OR
    ------------------------------

  • Steve Jorgensen
    Steve Jorgensen Member Posts: 8
    edited February 2023

    Does that mean that container parent/child is a kind of relationship that can be queried through /downstreamrelated ? How does that work, exactly?

    ------------------------------
    Steve Jorgensen
    Cliosoft
    OR
    ------------------------------
    -------------------------------------------
    Original Message:
    Sent: 02-09-2023 00:24
    From: Colin Marquardt
    Subject: Sensible and performant way to descendants of an item the REST API

    There is <a href="https://rest.jamasoftware.com/#operation_getChildItems">GET /items/{id}/children</a> as well as /downstreamrelated and /downstreamrelationships which should be helpful.



    ------------------------------
    Colin Marquardt
    Bosch Sensortec GmbH
    ------------------------------

    Original Message:
    Sent: 02-08-2023 14:20
    From: Steve Jorgensen
    Subject: Sensible and performant way to descendants of an item the REST API

    I have scoured the REST API documentation, and I don't see that there is any straightforward way to query for descendants or even just direct children of an item.

    The only technique that I have been able to figure out to get those is to first retrieve ALL of the items in a project, then determine their containership hierarchies via location.parent references, and then use identify which of the items are descendants of the starting item.

    Is there something I am missing, or is that a capability that can be added to a future release?



    ------------------------------
    Steve Jorgensen
    Cliosoft
    OR
    ------------------------------

  • Colin Marquardt
    Colin Marquardt Member, Data Exchange Posts: 15
    edited February 2023

    Actually, I haven't used the last two endpoints myself, so I don't know.

    ------------------------------
    Colin Marquardt
    Bosch Sensortec GmbH
    ------------------------------
    -------------------------------------------
    Original Message:
    Sent: 02-12-2023 21:34
    From: Steve Jorgensen
    Subject: Sensible and performant way to descendants of an item the REST API

    Does that mean that container parent/child is a kind of relationship that can be queried through /downstreamrelated ? How does that work, exactly?

    ------------------------------
    Steve Jorgensen
    Cliosoft
    OR
    ------------------------------

    Original Message:
    Sent: 02-09-2023 00:24
    From: Colin Marquardt
    Subject: Sensible and performant way to descendants of an item the REST API

    There is <a href="https://rest.jamasoftware.com/#operation_getChildItems">GET /items/{id}/children</a> as well as /downstreamrelated and /downstreamrelationships which should be helpful.



    ------------------------------
    Colin Marquardt
    Bosch Sensortec GmbH

    Original Message:
    Sent: 02-08-2023 14:20
    From: Steve Jorgensen
    Subject: Sensible and performant way to descendants of an item the REST API

    I have scoured the REST API documentation, and I don't see that there is any straightforward way to query for descendants or even just direct children of an item.

    The only technique that I have been able to figure out to get those is to first retrieve ALL of the items in a project, then determine their containership hierarchies via location.parent references, and then use identify which of the items are descendants of the starting item.

    Is there something I am missing, or is that a capability that can be added to a future release?



    ------------------------------
    Steve Jorgensen
    Cliosoft
    OR
    ------------------------------

  • Steve Jorgensen
    Steve Jorgensen Member Posts: 8
    edited February 2023

    Great! I'll try that.



    ------------------------------
    Steve Jorgensen
    Cliosoft
    OR
    ------------------------------
    -------------------------------------------
    Original Message:
    Sent: 02-09-2023 09:19
    From: Nick McHale
    Subject: Sensible and performant way to descendants of an item the REST API

    Hi Steve,

    The most efficient way to fetch an entire subtree of items is to use the GET /abstractitems endpoint.  You can apply two filters to achieve the desired result.

    1. Use the project parameter to filter items from the current project.
    2. Use the contains parameter to filter items that match your parent items sequence number using Lucene search (https://dev.jamasoftware.com/cookbook/#abstract-lucene-parameters)
      For example, to fetch all descendants of the item with sequence number 2.4 you would enter the following into the contains field: "sequence: 2.4.*"

    I hope this helps.



    ------------------------------
    Nick McHale
    Team Lead - Software Engineer
    Jama Software
    Portland OR
    ------------------------------

    Original Message:
    Sent: 02-08-2023 14:20
    From: Steve Jorgensen
    Subject: Sensible and performant way to descendants of an item the REST API

    I have scoured the REST API documentation, and I don't see that there is any straightforward way to query for descendants or even just direct children of an item.

    The only technique that I have been able to figure out to get those is to first retrieve ALL of the items in a project, then determine their containership hierarchies via location.parent references, and then use identify which of the items are descendants of the starting item.

    Is there something I am missing, or is that a capability that can be added to a future release?



    ------------------------------
    Steve Jorgensen
    Cliosoft
    OR
    ------------------------------

  • Steve Jorgensen
    Steve Jorgensen Member Posts: 8
    edited February 2023

    That works great! The documentation could definitely be a little more clear regarding the behavior with respect to surrounding quotes, etc. Currently, some experimentation is required to figure out when surrounding quotes are needed and how they will behave.



    ------------------------------
    Steve Jorgensen
    Cliosoft
    OR
    ------------------------------
    -------------------------------------------
    Original Message:
    Sent: 02-09-2023 09:19
    From: Nick McHale
    Subject: Sensible and performant way to descendants of an item the REST API

    Hi Steve,

    The most efficient way to fetch an entire subtree of items is to use the GET /abstractitems endpoint.  You can apply two filters to achieve the desired result.

    1. Use the project parameter to filter items from the current project.
    2. Use the contains parameter to filter items that match your parent items sequence number using Lucene search (https://dev.jamasoftware.com/cookbook/#abstract-lucene-parameters)
      For example, to fetch all descendants of the item with sequence number 2.4 you would enter the following into the contains field: "sequence: 2.4.*"

    I hope this helps.



    ------------------------------
    Nick McHale
    Team Lead - Software Engineer
    Jama Software
    Portland OR
    ------------------------------

    Original Message:
    Sent: 02-08-2023 14:20
    From: Steve Jorgensen
    Subject: Sensible and performant way to descendants of an item the REST API

    I have scoured the REST API documentation, and I don't see that there is any straightforward way to query for descendants or even just direct children of an item.

    The only technique that I have been able to figure out to get those is to first retrieve ALL of the items in a project, then determine their containership hierarchies via location.parent references, and then use identify which of the items are descendants of the starting item.

    Is there something I am missing, or is that a capability that can be added to a future release?



    ------------------------------
    Steve Jorgensen
    Cliosoft
    OR
    ------------------------------

  • [Deleted User]
    [Deleted User] Posts: 103
    edited February 2023

    parent/child is not a Jama Relationship, so /downstreamrelated and /downstreamrelationships would not apply to parent/child requests.

    GET /items/{id}/children only gets the immediate children of the item, not the entire tree below the item.

    So I believe Nick's suggestion is the only one that would apply to this use case.

    ------------------------------
    Geoffrey Clemm
    Jama Software
    ------------------------------
    -------------------------------------------
    Original Message:
    Sent: 02-09-2023 00:24
    From: Colin Marquardt
    Subject: Sensible and performant way to descendants of an item the REST API

    There is <a href="https://rest.jamasoftware.com/#operation_getChildItems">GET /items/{id}/children</a> as well as /downstreamrelated and /downstreamrelationships which should be helpful.



    ------------------------------
    Colin Marquardt
    Bosch Sensortec GmbH
    ------------------------------

    Original Message:
    Sent: 02-08-2023 14:20
    From: Steve Jorgensen
    Subject: Sensible and performant way to descendants of an item the REST API

    I have scoured the REST API documentation, and I don't see that there is any straightforward way to query for descendants or even just direct children of an item.

    The only technique that I have been able to figure out to get those is to first retrieve ALL of the items in a project, then determine their containership hierarchies via location.parent references, and then use identify which of the items are descendants of the starting item.

    Is there something I am missing, or is that a capability that can be added to a future release?



    ------------------------------
    Steve Jorgensen
    Cliosoft
    OR
    ------------------------------

  • Folkert Roscam Abbing
    Folkert Roscam Abbing Member Posts: 9

    I tried the approach given above:

    Use the GET /abstractitems using (literally, including quotes) "sequence":"2.*" to search for all items with a sequence starting with 2.*.

    However, I also get item 3.2.* etc., so it also searches in the middle of the "sequence" field. Is there a key to signal that it must look only for terms STARTING at with 2.*?

  • Folkert Roscam Abbing
    Folkert Roscam Abbing Member Posts: 9

    Question to the Jama insiders: what version of Lucene is used?

    I can find some information online about the syntax, e.g. https://lucene.apache.org/core/2_9_4/queryparsersyntax.html#:~:text=Although%20Lucene%20provides%20the%20ability%20to%20create%20your%20own%20queries%23:~:text=Although%20Lucene%20provides%20the%20ability%20to%20create%20your%20own%20queries for version 2.9.4. This page does not mention any syntax to address the above issue and it explicitly states that the query can be subject to change between versions.

    Please help me out with this. Thanks!

Categories