Recently we launched v201004, and with that introduced the new Statement object which gives support for one of our top requested features - bind variables. In this blog post, we will take a closer look at the Publisher Query Language (PQL), Statements with bind variables, and what we have in store for the future.
Publisher Query Language
PQL plays a very significant role in the DFP API by providing the developer with a robust way of filtering which objects should be retrieved or modified before the request is completed. In other words, if you would like to retrieve only orders which are in the draft state, you could take one of two approaches. You could fetch all orders within your network and filter them one by one or instruct the server to only fetch orders in the draft state before returning all results. By doing the latter, the DFP API allows developers to create smaller and more direct requests, and, in turn, increases the efficiency of their code.
PQL has a very similar syntax to SQL, but does not include keywords such as SELECT or FROM; they are implied by the method which uses the PQL statement. The following piece of code constructs a Statement capable of fetching orders in the draft state and retrieves those orders:
// Create a statement to only select orders in the
// 'DRAFT' state.
Statement filterStatement = new Statement();
filterStatement.setQuery("WHERE status = 'DRAFT' LIMIT 500");
OrderPage orderPage =
orderService.getOrdersByStatemet(filterStatement);
The documentation included for each "get*ByStatment" (e.g. getOrdersByStatement) method indicates which PQL fields map to which object properties.
Paging
The result for "get*ByStatment" calls are pages specific to the service; i.e. an OrderPage is returned by getOrdersByStatement. The limit for the number of objects that can be fetched for a single PQL request, and in a single Page, is 500. Because of this, you should always include LIMIT 500 in your statement. However, if you would like to fetch more than 500 objects, you will need to page through the results by including an OFFSET <#> in your statement as well. To page through orders in groups of 500, for example, in your statement, you would include LIMIT 500 as well as an OFFSET of an interval of 500.
This can be represented by the following code:
Publisher Query Language
PQL plays a very significant role in the DFP API by providing the developer with a robust way of filtering which objects should be retrieved or modified before the request is completed. In other words, if you would like to retrieve only orders which are in the draft state, you could take one of two approaches. You could fetch all orders within your network and filter them one by one or instruct the server to only fetch orders in the draft state before returning all results. By doing the latter, the DFP API allows developers to create smaller and more direct requests, and, in turn, increases the efficiency of their code.
PQL has a very similar syntax to SQL, but does not include keywords such as SELECT or FROM; they are implied by the method which uses the PQL statement. The following piece of code constructs a Statement capable of fetching orders in the draft state and retrieves those orders:
// Create a statement to only select orders in the
// 'DRAFT' state.
Statement filterStatement = new Statement();
filterStatement.setQuery("WHERE status = 'DRAFT' LIMIT 500");
OrderPage orderPage =
orderService.getOrdersByStatemet(filterStatement);
The documentation included for each "get*ByStatment" (e.g. getOrdersByStatement) method indicates which PQL fields map to which object properties.
Paging
The result for "get*ByStatment" calls are pages specific to the service; i.e. an OrderPage is returned by getOrdersByStatement. The limit for the number of objects that can be fetched for a single PQL request, and in a single Page, is 500. Because of this, you should always include LIMIT 500 in your statement. However, if you would like to fetch more than 500 objects, you will need to page through the results by including an OFFSET <#> in your statement as well. To page through orders in groups of 500, for example, in your statement, you would include LIMIT 500 as well as an OFFSET of an interval of 500.
This can be represented by the following code:
