Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

PPL geoip function #781

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
+48 −0
Draft

PPL geoip function #781

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions docs/ppl-lang/planning/ppl-geoip.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
## geoip syntax proposal

geoip function to add information about the geographical location of an IPv4 or IPv6 address

1. **Proposed syntax**
- `... | eval geoinfo = geoip([datasource,] ipAddress [,properties])`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what does datasource mean? Could you use other meaningful usage rather that abc? abc is not straightforward user case.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

datasource refers to the datasources provided by the ip2geo processor, see #781 (comment)

- generic syntax
- `... | eval geoinfo = geoip(ipAddress)`
- use the default geoip datasource
- `... | eval geoinfo = geoip("abc", ipAddress)`
- use the "abc" geoip datasource
- `... | eval geoinfo = geoip(ipAddress, "city,lat,lon")`
- use the default geoip datasource, retrieve only city, lat and lon
- `... | eval geoinfo = geoip("abc", ipAddress, "city,lat,lon")`
- use the "abc" geoip datasource, retrieve only city, lat and lon


2. **Proposed wiring with the geoip database**
- Leverage the functionality of the ip2geo processor
- ip2geo processor configuration, functionality and code will be used
- Prerequisite for the geoip is that ip2geo processor is configured properly
- See https://opensearch.org/docs/latest/ingest-pipelines/processors/ip2geo/


### New syntax definition in ANTLR
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As a user doc, could we remove the ANTLR related information, what here needs is just a user readable syntax definition.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, the file is located ppl-lang/planning folder. I think we need an user doc instead of design doc. We can copy this design information to the PR description or issue description. And you can easily update your design without any code changes.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@YANG-DB I did unterstand that the ppl-lang/planning folder is for design docs. When the design is approved it will be converted to a userdoc and moved out of the planning sub-folder. Am I wrong with that assumption?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought it was for roadmap. I prefer to using GitHub PR description and comments. It's fine to add design docs in code if you prefer to. But these docs are not for users, we need to write a new one later.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@salyh yes - once design doc is approved we will move it with necessary updates to the regular commands folder


```ANTLR

// functions
evalFunctionCall
: evalFunctionName LT_PRTHS functionArgs RT_PRTHS
| geoipFunction
;

geoipFunction
: GEOIP LT_PRTHS (datasource = functionArg COMMA)? ipAddress = functionArg (COMMA properties = stringLiteral)? RT_PRTHS
;
```

3 changes: 3 additions & 0 deletions ppl-spark-integration/src/main/antlr4/OpenSearchPPLLexer.g4
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -372,6 +372,9 @@ TYPEOF: 'TYPEOF';
//OTHER CONDITIONAL EXPRESSIONS
COALESCE: 'COALESCE';

//GEOLOCATION FUNCTIONS
GEOIP: 'GEOIP';

// RELEVANCE FUNCTIONS AND PARAMETERS
MATCH: 'MATCH';
MATCH_PHRASE: 'MATCH_PHRASE';
Expand Down
6 changes: 6 additions & 0 deletions ppl-spark-integration/src/main/antlr4/OpenSearchPPLParser.g4
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -465,6 +465,7 @@ wcFieldExpression
// functions
evalFunctionCall
: evalFunctionName LT_PRTHS functionArgs RT_PRTHS
| geoipFunction
;

// cast function
Expand Down Expand Up @@ -781,6 +782,10 @@ coalesceFunctionName
: COALESCE
;

geoipFunction
: GEOIP LT_PRTHS (datasource = functionArg COMMA)? ipAddress = functionArg (COMMA properties = stringLiteral)? RT_PRTHS
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

datasource = functionArg

Any case for supporting functionArg instead of stringLiteral. Again, what does datasource mean?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no particular case for functionArg. We can change it to stringLiteral for sure

datasource refers to the datasources provided by the ip2geo processor, see #781 (comment)

;

// operators
comparisonOperator
: EQUAL
Expand Down Expand Up @@ -1051,4 +1056,5 @@ keywordsCanBeId
| FULL
| SEMI
| ANTI
| GEOIP
;
Loading