flink-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From alpinegizmo <...@git.apache.org>
Subject [GitHub] flink pull request #4041: [FLINK-6198] [cep] Update CEP documentation.
Date Fri, 02 Jun 2017 15:57:42 GMT
Github user alpinegizmo commented on a diff in the pull request:

    https://github.com/apache/flink/pull/4041#discussion_r119853002
  
    --- Diff: docs/dev/libs/cep.md ---
    @@ -98,48 +128,106 @@ val result: DataStream[Alert] = patternStream.select(createAlert(_))
     </div>
     </div>
     
    -Note that we use Java 8 lambdas in our Java code examples to make them more succinct.
    -
     ## The Pattern API
     
    -The pattern API allows you to quickly define complex event patterns.
    -
    -Each pattern consists of multiple stages or what we call states.
    -In order to go from one state to the next, the user can specify conditions.
    -These conditions can be the contiguity of events or a filter condition on an event.
    -
    -Each pattern has to start with an initial state:
    -
    -<div class="codetabs" markdown="1">
    -<div data-lang="java" markdown="1">
    -{% highlight java %}
    -Pattern<Event, ?> start = Pattern.<Event>begin("start");
    -{% endhighlight %}
    -</div>
    -
    -<div data-lang="scala" markdown="1">
    -{% highlight scala %}
    -val start : Pattern[Event, _] = Pattern.begin("start")
    -{% endhighlight %}
    -</div>
    -</div>
    -
    -Each state must have a unique name to identify the matched events later on.
    -Additionally, we can specify a filter condition for the event to be accepted as the start
event via the `where` method.
    -These filtering conditions can be either an `IterativeCondition` or a `SimpleCondition`.

    -
    -**Iterative Conditions:** This type of conditions can iterate over the previously accepted
elements in the pattern and 
    -decide to accept a new element or not, based on some statistic over those elements. 
    -
    -Below is the code for an iterative condition that accepts elements whose name start with
"foo" and for which, the sum 
    -of the prices of the previously accepted elements for a state named "middle", plus the
price of the current event, do 
    -not exceed the value of 5.0. Iterative condition can be very powerful, especially in
combination with quantifiers, e.g.
    -`oneToMany` or `zeroToMany`.
    +The pattern API allows you to quickly define complex pattern sequences that you want
to extract 
    +from your input stream.
    +
    +Each such complex pattern sequence consists of multiple simple patterns, i.e. patterns
looking for 
    +individual events with the same properties. These simple patterns are called **states**.
A complex pattern 
    +can be seen as a graph of such states, where transition from one state to the next happens
based on user-specified
    +*conditions*, e.g. `event.getName().equals("start")`. A *match* is a sequence of input
events which visit all 
    +states of the complex pattern graph, through a sequence of valid state transitions.
    +
    +<span class="label label-danger">Attention</span> Each state must have a
unique name to identify the matched 
    +events later on. 
    +
    +<span class="label label-danger">Attention</span> State names **CANNOT**
contain the character `:`.
    +
    +In the remainder, we start by describing how to define [States](#states), before describing
how you can 
    +combine individual states into [Complex Patterns](#combining-states).
    +
    +### Individual States
    +
    +A **State** can be either a *singleton* state, or a *looping* one. Singleton states accept
a single 
    +event, while looping ones can accept more than one. In pattern matching symbols, in the
pattern `a b+ c? d` (or `a`, 
    +followed by *one or more* `b`'s, optionally followed by a `c`, followed by a `d`), `a`,
`c?`, and `d` are 
    +singleton patterns, while `b+` is a looping one. By default, a state is a singleton state
and you can transform 
    +it to a looping one using [Quantifiers](#quantifiers). In addition, each state can have
one or more 
    +[Conditions](#conditions) based on which it accepts events.
    +
    +#### Quantifiers
    +
    +In FlinkCEP, looping patterns can be specified using the methods: `pattern.oneOrMore()`,
for states that expect one or
    +more occurrences of a given event (e.g. the `b+` mentioned previously), and `pattern.times(#ofTimes)`
for states that 
    +expect a specific number of occurrences of a given type of event, e.g. 4 `a`'s. All states,
looping or not, can be made 
    +optional using the `pattern.optional()` method. For a state named `start`, the following
are valid quantifiers:
    + 
    + <div class="codetabs" markdown="1">
    + <div data-lang="java" markdown="1">
    + {% highlight java %}
    + // expecting 4 occurrences
    + start.times(4);
    +  
    + // expecting 0 or 4 occurrences
    + start.times(4).optional();
    + 
    + // expecting 1 or more occurrences
    + start.oneOrMore();
    +   
    + // expecting 0 or more occurrences
    + start.oneOrMore().optional();
    + {% endhighlight %}
    + </div>
    + 
    + <div data-lang="scala" markdown="1">
    + {% highlight scala %}
    + // expecting 4 occurrences
    + start.times(4)
    +   
    + // expecting 0 or 4 occurrences
    + start.times(4).optional()
    +  
    + // expecting 1 or more occurrences
    + start.oneOrMore()
    +    
    + // expecting 0 or more occurrences
    + start.oneOrMore().optional()
    + {% endhighlight %}
    + </div>
    + </div>
    +
    +#### Conditions
    +
    +At every state, and in order to go from one state to the next, you can specify additional
**conditions**. 
    +These conditions can be related to:
    + 
    + 1. a [property of the incoming event](#conditions-on-properties), e.g. its value should
be larger than 5, 
    + or larger than the average value of the previously accepted events.
    +
    + 2. the [contiguity of the matching events](#conditions-on-contiguity), e.g. detect pattern
`a,b,c` without 
    + non-matching events between any matching ones.
    + 
    +The latter refers to "looping" states, i.e. states that can accept more than one event,
e.g. the `b+` in `a b+ c`, 
    +which searches for one or more `b`'s.
    +
    +##### Conditions on Properties
    +
    +Conditions on the event properties can be specified via the `pattern.where()` method.
These can be either 
    +`IterativeCondition`s or `SimpleCondition`s.
    +
    +**Iterative Conditions:** This is the most general type of conditions. This allows to
specify a condition that accepts 
    +any subsequent event based on some statistic over a subset of the previously accepted
events. 
    +
    +Below is the code for an iterative condition that accepts the next event for a state
named "middle" if its name starts 
    +with "foo" and the sum of the prices of the previously accepted events for that state
plus the price of the current 
    +event, do not exceed the value of 5.0. Iterative conditions can be very powerful, especially
in combination with looping 
    --- End diff --
    
    The comma doesn't work where it is. I suggest
    
    Below is the code for an iterative condition that accepts the next event for a state named
"middle" if its name starts with "foo", and if the sum of the prices of the previously accepted
events for that state plus the price of the current event do not exceed the value of 5.0.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

Mime
View raw message