some Filter vs. Direct Line Filtering

Context

When querying documents (such as Sales Quotes, Sales Orders, Sales Delivery Notes, and Sales Invoices) in GraphQL, there are two primary methods to filter based on line items:

using a some filter within the document query,
or querying document lines directly with a filter.

Each method has different use cases and produces distinct results.

Differences Between the Two Approaches

Using a some filter in document queries allows you to retrieve documents that have at least one line item meeting a specific condition.
However, all line items associated with those documents are returned, regardless of whether they meet the filter criteria.
Directly querying document lines applies the filter at the line item level, meaning only the lines that satisfy the specified condition are returned, independent of other lines in the document.

Examples

Using `some` Filter in Document Query

Retrieve all invoices between two dates where the product CLMENWATCH has been sold.
In this example, all salesInvoices that have at least one line selling the product CLMENWATCH within the specified date range will be retrieved. Note that all lines of these invoices are returned, even if some do not contain the product CLMENWATCH.

 query {
   salesInvoices (
       order: { documentDate: DESC },
       where: {
       and: [
           { documentDate: { gte: "2024-01-01" } },
           { documentDate: { lte: "2024-12-31" } },
           { lines: { some: { 
                productCode : {eq :"CLMENWATCH"}
           }}}
       ]
       }
   ) {
       edges {
       node {
           id
           socialName
           operationalNumber
           creationDate
           lines {
           productCode
           productName
           totalQuantity
           }
       }
       }
   }
 }

Invoice ID	Social Name	Operational Number	Creation Date	Product Code	Product Name	Quantity
INV12345	ABC Corp	123456	2024-03-10	CLMENWATCH	Classic Men’s Watch	10
				SILVCHAIN	Silver Chain	5
				GLDRING	Gold Ring	2
INV12346	XYZ Ltd	789012	2024-03-12	DIAMRINGS	Diamond Rings	7
				PRLNECKLACE	Pearl Necklace	3
				CLMENWATCH	Classic Men’s Watch	8
				SAPHCHOKER	Sapphire Choker	4

Direct Line Filtering

Retrieve quantities and sales prices of the product CLMENWATCH sold between two dates.
In this example, only the lines where the product CLMENWATCH is sold within the specified date range are retrieved. The query returns relevant line details, such as quantity and unit price, along with the associated sales invoice information.

query {
 salesInvoiceLines(
     order: { salesInvoice: { documentDate: DESC } },
     where: {
     and: [
         { salesInvoice: { documentDate: { gte: "2024-01-01" } } },
         { salesInvoice: { documentDate: { lte: "2024-12-31" } } },
         { productCode: { eq: "CLMENWATCH" } }
     ]
     }
 ) {
     edges {
     node {
         salesInvoice {
         id
         operationalNumber
         documentDate
         }
         productCode
         productName
         totalQuantity
         unitPrice
         totalNet
     }
     }
 }
 }

Invoice ID	Social Name	Operational Number	Creation Date	Product Code	Product Name	Total Quantity
INV12345	ABC Corp	123456	2024-03-10	CLMENWATCH	Classic Men’s Watch	10
INV12346	XYZ Ltd	789012	2024-03-12	CLMENWATCH	Classic Men’s Watch	8

Recommendation

Select the approach that best fits your data retrieval requirements:

Use document queries with a some filter when you need to retrieve entire documents while still considering all their associated line items.
Use direct document line filtering when focusing solely on line items that meet certain criteria, without including the rest of the document’s lines.

Caution

Understand that using the some filter will return the entire document with all its lines, not just the ones that match the filter condition.
This could lead to retrieving more data than necessary, which might impact performance or require additional processing.