diff --git a/docs/query-language.md b/docs/query-language.md index 7c54c3ba8..f866a1e27 100644 --- a/docs/query-language.md +++ b/docs/query-language.md @@ -21,7 +21,7 @@ This section will provide a detailed reference and examples for the Pilosa Query There will be one item in the `results` array for each PQL query in the request. The type of each item in the array will depend on the type of query - each query in the reference below lists it's result type. -Row and Column labels are set and frame and index creation time respectively. When the specification of a query says *row_label* or *col_label*, one should use the labels that were set while creating the index and frame. The default row label is `id`, and the default column label is `columnID`. +The default row label is `rowID`, and the default column label is `columnID`. Changing these defaults is deprecated and this feature will be removed in a future release. #### Conventions @@ -33,18 +33,18 @@ Row and Column labels are set and frame and index creation time respectively. Wh Before running any of the example queries below, follow the instructions in the [Getting Started](../getting-started) section to set up an index, frames, and populate them with some data. -The examples just show the PQL quer(ies) needed - to run the query `SetBit(frame="stargazer", repo_id=10, stargazer_id=1)` against a server using curl, you would: +The examples just show the PQL quer(ies) needed - to run the query `SetBit(frame="stargazer", columnID=10, rowID=1)` against a server using curl, you would: ``` curl localhost:10101/index/repository/query \ -X POST \ - -d 'SetBit(frame="stargazer", repo_id=10, stargazer_id=1)' + -d 'SetBit(frame="stargazer", columnID=10, rowID=1)' ``` #### Arguments and Types * `frame` The frame specifies on which Pilosa [frame]({{< ref "glossary.md#frame" >}}) the query will operate. Valid frame names are lower case strings; they start with an alphanumeric character, and contain only alphanumeric characters and `_-`. They must be 64 characters or less in length. -* `ROW_LABEL` Pilosa allows users to set different row labels for each frame at frame creation time. The default row label is `rowID`, but one may set a more descriptive row label for their data (such as `stargazer_id`). -* `COL_LABEL` Pilosa allows users to set a different column label for each index at index creation time. The default column label is `columnID`. +* `ROW_LABEL` The default row label is `rowID`, changing the default is deprecated. +* `COL_LABEL` The default column label is `columnID`, changing the default is deprecated. * `TIMESTAMP` This is a timestamp in quotes with the following format `"YYYY-MM-DDTHH:MM"` (e.g. "2006-01-02T15:04") * `UINT` An unsigned integer (e.g. 42839) * `ATTR_NAME` Must be a valid identifier `[A-Za-z][A-Za-z0-9._-]*` @@ -77,19 +77,19 @@ A return value of `false` indicates that the bit was already set to 1 and nothin **Examples:** ``` -SetBit(frame="stargazer", repo_id=10, stargazer_id=1) +SetBit(frame="stargazer", repo_id=10, rowID=1) ``` This query illustrates setting a bit in the stargazer frame. User with id=1 has starred repository with id=10. SetBit also supports providing a timestamp. To write the date that a user starred a repository. ``` -SetBit(frame="stargazer", repo_id=10, stargazer_id=1, timestamp="2016-01-01T00:00") +SetBit(frame="stargazer", repo_id=10, rowID=1, timestamp="2016-01-01T00:00") ``` Setting multiple bits in a single request: ``` -SetBit(frame="stargazer", repo_id=10, stargazer_id=1) SetBit(frame="stargazer", repo_id=10, stargazer_id=2) SetBit(frame="stargazer", repo_id=20, stargazer_id=1) SetBit(frame="stargazer", repo_id=30, stargazer_id=2) +SetBit(frame="stargazer", columnID=10, rowID=1) SetBit(frame="stargazer", columnID=10, rowID=2) SetBit(frame="stargazer", columnID=20, rowID=1) SetBit(frame="stargazer", columnID=30, rowID=2) ``` #### SetRowAttrs @@ -112,13 +112,13 @@ SetRowAttrs queries always return `null` upon success. **Examples:** ``` -SetRowAttrs(frame="stargazer", stargazer_id=10, username="mrpi", active=true) +SetRowAttrs(frame="stargazer", rowID=10, username="mrpi", active=true) ``` Set username value and active status for user 10. These are arbitrary key/value pairs which have no meaning to Pilosa. You can see the attributes you've set on a row with a [Bitmap]({{< ref "query-language.md#bitmap" >}}) query like so `Bitmap(frame="stargazer", stargazer_id=10)`. ``` -SetRowAttrs(frame="stargazer", stargazer_id=10, username=null) +SetRowAttrs(frame="stargazer", rowID=10, username=null) ``` Delete username value for user 10. @@ -144,13 +144,13 @@ SetColumnAttrs queries always return `null` upon success. Setting a value of `nu **Examples:** ``` -SetColumnAttrs(repo_id=10, stars=123, url="http://projects.pilosa.com/10", active=true) +SetColumnAttrs(columnID=10, stars=123, url="http://projects.pilosa.com/10", active=true) ``` Set url value and active status for project 10. These are arbitrary key/value pairs which have no meaning to Pilosa. You can see the attributes you've set on a column with a [Bitmap]({{< ref "query-language.md#bitmap" >}}) query like so `Bitmap(frame="stargazer", repo_id=10)`. ``` -SetColumnAttrs(repo_id=10, url=null) +SetColumnAttrs(columnID=10, url=null) ``` Delete url value for repo 10. @@ -178,7 +178,7 @@ A return value of `false` indicates that the bit was already set to 0 and nothin **Examples:** ``` -ClearBit(frame="stargazer", repo_id=10, stargazer_id=1) +ClearBit(frame="stargazer", columnID=10, rowID=1) ``` Remove relationship between stargazer_id 1 and repo_id 10 from the stargazer frame. @@ -206,7 +206,7 @@ e.g. `{"attrs":{"username":"mrpi","active":true},"bits":[10, 20]}` Query all repositories that user 1 has starred. ``` -Bitmap(frame="stargazer", stargazer_id=1) +Bitmap(frame="stargazer", rowID=1) ``` Returns `{"attrs":{"username":"mrpi","active":true},"bits":[10, 20]}` @@ -263,7 +263,7 @@ attrs will always be empty Query repositories which have been starred by two users. ``` -Intersect(Bitmap(frame="stargazer", stargazer_id=1), Bitmap(frame="stargazer", stargazer_id=2)) +Intersect(Bitmap(frame="stargazer", rowID=1), Bitmap(frame="stargazer", rowID=2)) ``` Returns `{"attrs":{},"bits":[10]}`. @@ -290,7 +290,7 @@ attrs will always be empty Query repositories which have been starred by one user and not another. ``` -Difference(Bitmap(frame="stargazer", stargazer_id=1), Bitmap( frame="stargazer", stargazer_id=2)) +Difference(Bitmap(frame="stargazer", rowID=1), Bitmap( frame="stargazer", rowID=2)) ``` Return `{"results":[{"attrs":{},"bits":[20]}]}` @@ -298,7 +298,7 @@ Return `{"results":[{"attrs":{},"bits":[20]}]}` * bits are repositories that were starred by user 1 BUT NOT user 2 ``` -Difference(Bitmap(frame="stargazer", stargazer_id=2), Bitmap( frame="stargazer", stargazer_id=1)) +Difference(Bitmap(frame="stargazer", rowID=2), Bitmap( frame="stargazer", rowID=1)) ``` Return `{"attrs":{},"bits":[30]}` @@ -322,7 +322,7 @@ Returns the number of set bits in the `BITMAP_CALL` passed in. Query the number of repositories to which a user has contributed. ``` -Count(Bitmap(frame="stargazer", stargazer_id=1)) +Count(Bitmap(frame="stargazer", rowID=1)) ``` Return `2` @@ -386,7 +386,7 @@ Returns `[{"key": 1, "count": 2}, {"key": 2, "count": 2}]` * Results are the top two users sorted by number of repositories they've starred in descending order. ``` -TopN(Bitmap(frame="language", language_id=1), frame="stargazer", n=2) +TopN(Bitmap(frame="language", rowID=1), frame="stargazer", n=2) ``` Returns `[{"key": 1, "count": 2}, {"key": 2, "count": 1}]` @@ -414,7 +414,7 @@ between the given `start` and `end` timestamps. When you set timestamp using SetBit, you will able to query all repositories that a user has starred within a date range. ``` -Range(frame="stargazer", stargazer_id=1, start="2010-01-01T00:00", end="2017-03-02T03:00") +Range(frame="stargazer", rowID=1, start="2010-01-01T00:00", end="2017-03-02T03:00") ``` Returns `{{"attrs":{},"bits":[10]}`