Skip to content

Commit

Permalink
Update READMe
Browse files Browse the repository at this point in the history
  • Loading branch information
@esmarkowski
esmarkowski committed Mar 11, 2024
1 parent 2e18581 commit 292901f
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 114 deletions.
121 changes: 10 additions & 111 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,21 @@ Stretchy provides Elasticsearch/Opensearch models in Rails applications with an
Stretchy simplifies the process of querying, aggregating, and managing Elasticsearch-backed models, allowing Rails developers to work with search indices as comfortably as they would with traditional Rails models.

* Model fully back by Elasticsearch/Opensearch
* Chain queries, scopes and aggregations
* Chain `queries`, `scopes` and `aggregations`
* Reduce Elasticsearch query complexity
* Support for time-based indices and aliases
* Associations to both ActiveRecord models and Stretchy::Record
* Associations to both ActiveRecord models and `Stretchy::Record`
* Bulk Operations made easy
* Validations, custom attributes, and more...

Follow the guides to learn more about:
* [Models](guides/models?id=models)
* [Querying](guides/querying?id=querying)
* [Aggregations](guides/aggregations?id=aggregations)
* [Scopes](guides/scopes?id=scopes)

or walk through of a simple [Data Analysis](examples/data_analysis?id=data-analysis) example.

## Installation

Install the gem and add to the application's Gemfile by executing:
Expand Down Expand Up @@ -67,115 +75,6 @@ end
```
</details>

## Models

### Attributes

```ruby
class Post < Stretchy::Record

attribute :title, :keyword
attribute :body, :string
attribute :flagged, :boolean, default: false
attribute :author, :hash
attribute :tags, :array, default: []

end
```
>`created_at`, `:updated_at` and `:id` are automatically added to all `Stretchy::Records`

### Query
```ruby
Post.where(title: :goat, flagged: false)
#=> <Post id: 309sXA2s, title: "goat", body: "...", flagged: false, author...>
```
Query object fields with dot notation
```ruby
Post.where('author.name': "Jadzia", flagged: true).first
#=> <Post id: aW02w3092, title: "Fun Cats", body: "...", flagged: true,
# author: {name: "Jadzia", age: 20}, tags: ["cat", "amusing"]>
```

> The `default_sort_key` is :created_at
### Aggregations
```ruby

result = Post.aggregation(:post_frequency,
date_histogram: {
field: :created_at,
calender_interval: :month
})

result.aggregations.post_frequency
#=> {buckets: [{key_as_string: "2024-01-01", doc_count: 20}, ...]}
```
### Query Filters

```ruby
Post.filter_query(:range, 'author.age': {gte: 18, lte: 30}).where(title: "Welcome")
#=> filters authors with age greater than 18 and less than 30
```

### Scopes
Scopes can contain any query methods, filters or aggregations, resulting in composable queries.
```ruby
class Post < Stretchy::Record
# ...attributes

# Scopes
scope :flagged, -> { where(flagged: true) }
scope :top_links, lambda do |size=10, url=".com"|
aggregation(:links,
terms: {
field: :links,
size: size,
include: ".*#{url}.*"
})
end
end

# Returns flagged posts and includes the top 10 'youtube.com'
# links in results.aggregations.links
result = Post.flagged.top_links(10, "youtube.com")

```

#### Shared scopes

```ruby
Post.using_time_based_indices(2.months.ago...Time.now).flagged
# searches across post_2024_01,post_2024_02,post_2024_03 indexes
```

```ruby
Post.between(12.days.ago...1.day.ago.end_of_day).where('author.name': "candy")
#=> Candy's posts created between 12 days ago and end of day yesterday
```

### Bulk Operations


```ruby
Model.bulk(records_as_bulk_operations)
```

#### Bulk helper
Generates structure for the bulk operation
```ruby
record.to_bulk # default to_bulk(:index)
record.to_bulk(:delete)
record.to_bulk(:update)
```

#### In batches
Run bulk operations in batches specified by `size`
```ruby
Model.bulk_in_batches(records, size: 100) do |batch|
batch.map! { |record| Model.new(record).to_bulk }
end
```


## Development
Expand Down
11 changes: 8 additions & 3 deletions docs/guides/querying.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,13 +69,18 @@ The `.filter_query` method is used to add conditions to the filter clause of the

This makes `.filter_query` useful for conditions that should exclude documents from the results, but should not affect how the remaining documents are ranked. For example, you might use `.filter_query` to exclude documents that are marked as 'deleted' or that fall outside a certain date range.

Here's an example of how you might use the `.filter_query` method:
In this example, the `.filter_query` method is used to exclude documents where the `deleted` field is `true` and where the `published_at` field is before '2022-01-01'. The remaining documents are ranked based on their relevance to the query, without considering the `deleted` and `published_at` fields.

```ruby
Model.filter_query(deleted: false, color: 'green')
Model.filter_query(:term, deleted: false, color: 'green')
```


In this example, the `.filter_query` is used to generate a `range` filter and include documents where `author.age` is between 18 and 30.
```ruby
Model.filter_query(:range, 'author.age': {gte: 18, lte: 30})
```

In this example, the `.filter_query` method is used to exclude documents where the `deleted` field is `true` and where the `published_at` field is before '2022-01-01'. The remaining documents are ranked based on their relevance to the query, without considering the `deleted` and `published_at` fields.

The `.filter_query` method returns a new `Stretchy::Relation` object, so you can chain other methods onto it to further refine your search.

Expand Down

0 comments on commit 292901f

Please sign in to comment.