Skip to content

Commit 55956ca

Browse files
SpamerczSpamercz
committed
Documentation
1 parent d62925c commit 55956ca

6 files changed

Lines changed: 136 additions & 28 deletions

File tree

‎doc/05_new_index_with_mapping.md‎

Lines changed: 36 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,49 @@
11
# Create index with mapping for entity
22

3-
Entity is configured (link) and defined in php (link) and next thing is to get these settings to ElasticSearch.
3+
Entity is configured [link](03_entity_class.md) and defined in php [link](03_entity_class.md#L247) and next thing is to get these settings to ElasticSearch.
44

55
## Index creating
66

7-
### New index - no previous data
8-
TODO
7+
### Variant 1. - No previous data
8+
- When to use?
9+
- You dont have any index, your ElasticSearch installation is clean and with no index for our entities.
10+
- How?
11+
- Simple neon is configured from previous [step](02_neon_configuration.md) and we just need to run command.
12+
913
```bash
1014
php www/index spameri:elastic:create-index
1115
```
1216

13-
### New index - deleting previous data
14-
TODO
17+
- Can be used for specific entity
18+
```bash
19+
php www/index spameri:elastic:create-index video
20+
```
1521

16-
### New index - preserving previous data
17-
TODO
1822

23+
### Variant 2. - Deleting previous data
24+
- When to use?
25+
- You have existing index with outdated data with old configuration, but you dont need to keep them. This is
26+
usually when you are generating ElasticSearch data from another database.
27+
- How?
28+
- Just add -f option. First thing command does is delete old index, then creating new empty index with new settings.
29+
```bash
30+
php www/index spameri:elastic:create-index -f
31+
```
1932

33+
- Can be used for specific entity
34+
```bash
35+
php www/index spameri:elastic:create-index -f video
36+
```
2037

38+
### Variant 3. - Preserving previous data
39+
- When to use?
40+
- You dont have source for data saved in ElasticSearch.
41+
- Best is backup your data with command. This creates bulk json document with all data from index.
42+
```bash
43+
php www/index spameri:elastic:dump-index
44+
```
45+
- With data backed up, now you can delete index and create it fresh with new mapping - following variant 2.
46+
- Last thing is get your old data to new index wit this command.
47+
```bash
48+
php www/index spameri:elastic:restore-index
49+
```

‎doc/06_fill_data.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,25 @@
11
# Create and save entity
22

33
## Create
4-
TODO
5-
[Example](../tests/SpameriTests/Model/Insert.phpt#L16)
4+
- When creating new entity, mostly you need to construct it manually.
5+
- Your data is from another database or API or csv or wherever. Quality may wary.
6+
- So best approach is to validate all you can with objects.
7+
- In this example we have property **imdb** and it needs to be in range from one digit to ten digits, rather than adding
8+
if conditions wherever we create entity we use **ImdbId** class to validate this rule and this helps to properly convert
9+
entity data to array.
10+
- [Example](../tests/SpameriTests/Model/Insert.phpt#L16)
611
```php
12+
$sqlData = $dibi->fetchRow();
713
$video = new \SpameriTests\Data\Entity\Video(
814
new \Spameri\Elastic\Entity\Property\EmptyElasticId(),
915
new \SpameriTests\Data\Entity\Video\Identification(
10-
new \SpameriTests\Data\Entity\Property\ImdbId(4154796)
16+
new \SpameriTests\Data\Entity\Property\ImdbId($sqlData['imdb'])
1117
)
1218
);
1319
```
1420

1521
## Save
16-
TODO
22+
- Entity is created, validated and ready to be saved. Just pass entity to [service](12_entity_service.md). And done.
1723
```php
1824
$videoService->insert($video);
1925
```
20-

‎doc/07_save_explained.md‎

Lines changed: 39 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,41 @@
11
# Insert explained
22

3-
- Converter
4-
- ElasticSearch point of view
5-
TODO
3+
## \Spameri\Elastic\Model\Insert\PrepareEntityArray
4+
- This class is responsible for converting ElasticSearch entity to array that can be then saved to ElasticSearch.
5+
- Configuring is done by implementing [interfaces](04_data_interfaces.md), no need for annotations or neon.
6+
7+
### ::prepare(\Spameri\Elastic\Entity\IElasticEntity $entity)
8+
- This method is here for last before convert modifications.
9+
- If implemented `\Spameri\Elastic\Entity\ITrackedEntity` interface for entity tracking (and properties specified),
10+
this method adds timestamp and user who edited/created entity.
11+
- Then calling iterateVariables to prepare rest of entity array.
12+
13+
### ::iterateVariables(array $variables)
14+
This method accepts entity variables and based on their type performs converting to array to ready entity for insert.
15+
There are 9 types of property handled:
16+
1. **\Spameri\Elastic\Entity\IElasticEntity** in this case service locator comes to play and locates service for related
17+
entity and saves connected entity. And prepares related entity's id to property. Because to ElasticSearch goes only
18+
string id.
19+
20+
2. **\Spameri\Elastic\Entity\IEntity** this is structural entity and is saved directly to parent entity. Its properties
21+
are iterated with `::iterateVariables($property->entityVariables())`
22+
23+
3. **\Spameri\Elastic\Entity\IValue** raw value in object, directly converted to array.
24+
25+
4. **\Spameri\Elastic\Entity\IEntityCollection** Collection of structural class **IEntity**, iterate and act as step 2.
26+
27+
5. **\Spameri\Elastic\Entity\IElasticEntityCollection** Collection of ElasticSearch entities **IElasticEntity**,
28+
iterate and act as step 1.
29+
30+
6. **\Spameri\Elastic\Entity\IValueCollection** Collection of **IValue**, iterate and act as step 3.
31+
32+
7. Scalar values **string**, **int**, **bool** or **NULL**, no action just pass to array.
33+
34+
8. **\Spameri\Elastic\Entity\DateTimeInterface** Date interface with specified format by this library so ElasticSearch
35+
can save it without problems.
36+
- **\Spameri\Elastic\Entity\Property\Date** for `Y-m-d` format
37+
- **\Spameri\Elastic\Entity\Property\DateTime** for `Y-m-d\TH:i:s` format
38+
39+
9. **\DateTime** All other Dates are converted to `Y-m-d\TH:i:s`
40+
41+
10. Exception thrown property is none of above.

‎doc/09_match_get.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,17 @@
11
# Filter data
22

33
## Description
4-
TODO
4+
You can specify complicated ElasticSearch Query and still get pretty entity. [Service](12_entity_service.md) accepts
5+
`\Spameri\ElasticQuery\ElasticQuery` object and returns entity or collection depending if you want one or more results.
56

67
## Example
8+
In this example we are looking for video named 'Avengers' made in years from 2017 to 2018.
79
```php
810
$elasticQuery = new \Spameri\ElasticQuery\ElasticQuery();
911
$elasticQuery->query()->must()->add(
1012
new \Spameri\ElasticQuery\Query\Range(
1113
'year',
12-
2018,
14+
2017,
1315
2019
1416
)
1517
);

‎doc/10_aggregate.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
# Aggregate
22

33
## Description
4-
TODO
4+
When aggregating you dont get directly entity just array data, for this we have `\Spameri\ElasticQuery\Response\ResultSearch`
5+
object to encapsulate result.
56

67
## Example
8+
In this example we want number of videos released in each year.
79
```php
810
$elasticQuery = new \Spameri\ElasticQuery\ElasticQuery();
911
$elasticQuery->aggregation()->add(

‎doc/13_advanced_get.md‎

Lines changed: 44 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,55 @@
11
# Advanced Get
22

33
## Description
4-
TODO
5-
Get data from ElasticSearch by tag.
4+
65

76
## Example
7+
In this example we want videos with tag **action** and are public. Also we want only first 50 sorted by year, but if
8+
year has multiple videos sort them by score. Bonus points if movie is on beach with someone named john or here
9+
misspelled as jon.
10+
11+
Query does not have to be specified all at once, this is demonstration of capabilities. Query can be constructed empty
12+
and extended through application runtime.
813
```php
9-
$video = $videoService->getBy(
10-
new \Spameri\ElasticQuery\ElasticQuery(
11-
new \Spameri\ElasticQuery\Query\QueryCollection(
12-
new \Spameri\ElasticQuery\Query\MustCollection(
13-
new \Spameri\ElasticQuery\Query\Match(
14-
'story.tag',
15-
'action'
16-
)
14+
$elasticQuery = new \Spameri\ElasticQuery\ElasticQuery(
15+
new \Spameri\ElasticQuery\Query\QueryCollection(
16+
new \Spameri\ElasticQuery\Query\MustCollection(
17+
new \Spameri\ElasticQuery\Query\Term(
18+
'story.tag',
19+
'action'
20+
),
21+
new \Spameri\ElasticQuery\Query\Term(
22+
'isPublic',
23+
TRUE
24+
)
25+
),
26+
new \Spameri\ElasticQuery\Query\ShouldCollection(
27+
new \Spameri\ElasticQuery\Query\Match(
28+
'story.description',
29+
'beach'
30+
),
31+
new \Spameri\ElasticQuery\Query\Fuzzy(
32+
'story.description',
33+
'jon'
34+
)
35+
)
36+
),
37+
NULL,
38+
NULL,
39+
new \Spameri\ElasticQuery\Options(
40+
50,
41+
NULL,
42+
new \Spameri\ElasticQuery\Options\SortCollection(
43+
new \Spameri\ElasticQuery\Options\Sort(
44+
'year',
45+
\Spameri\ElasticQuery\Options\Sort::DESC
46+
),
47+
new \Spameri\ElasticQuery\Options\Sort(
48+
'_score',
49+
\Spameri\ElasticQuery\Options\Sort::DESC
1750
)
1851
)
1952
)
2053
);
54+
$videos = $this->videoService->getAllBy($elasticQuery);
2155
```

0 commit comments

Comments
 (0)