{"id":18762576,"url":"https://github.com/hummingbird-me/typesensual","last_synced_at":"2025-06-12T06:12:07.382Z","repository":{"id":183319295,"uuid":"646301248","full_name":"hummingbird-me/typesensual","owner":"hummingbird-me","description":"A pleasing, sensual wrapper around Typesense's ruby library","archived":false,"fork":false,"pushed_at":"2024-10-06T07:49:44.000Z","size":160,"stargazers_count":3,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-06T10:41:56.579Z","etag":null,"topics":["ruby","typesense"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hummingbird-me.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-28T00:01:28.000Z","updated_at":"2024-10-06T07:49:46.000Z","dependencies_parsed_at":"2023-07-23T23:44:40.039Z","dependency_job_id":"de27a3a9-ac17-4253-af4c-c37c57142025","html_url":"https://github.com/hummingbird-me/typesensual","commit_stats":null,"previous_names":["hummingbird-me/typesensual"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummingbird-me%2Ftypesensual","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummingbird-me%2Ftypesensual/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummingbird-me%2Ftypesensual/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummingbird-me%2Ftypesensual/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hummingbird-me","download_url":"https://codeload.github.com/hummingbird-me/typesensual/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummingbird-me%2Ftypesensual/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259187413,"owners_count":22818770,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ruby","typesense"],"created_at":"2024-11-07T18:22:05.856Z","updated_at":"2025-06-12T06:12:07.355Z","avatar_url":"https://github.com/hummingbird-me.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Typesensual\n\nTypesensual is a small wrapper around the [Typesense Ruby client][typesense-gem] which provides a\nmore familiar, rubyish interface for interacting with [Typesense][typesense-website]. Similar to\n[Chewy][chewy-gem], it provides a DSL for defining your schema, manages the life-cycle of your\ncollections, and provides a simple interface for indexing, searching, and deleting documents.\n\nUnlike Chewy, it does *not* handle loading, denormalizing, or formatting your data for search\npurposes. It can be combined with an ORM such as ActiveRecord or Sequel, or even used with plain SQL\nqueries, but that integration is left to you. This is a concious decision, since loading and\ntransforming data is often a complex and application-specific task that is best left to the\napplication developer, since you know best.\n\n[typesense-gem]: https://github.com/typesense/typesense-ruby\n[typesense-website]: https://typesense.org/\n[chewy-gem]: https://github.com/toptal/chewy\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'typesensual'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install typesensual\n\n## Usage\n\n### Configuring the client\n\nThe first step is to configure the client. This is done by calling `Typesensual.configure` and\npassing a block to configure your parameters:\n\n```ruby\n# config/initializers/typesensual.rb\nTypesensual.configure do |config|\n  # The nodes in your cluster to connect to\n  config.nodes = [{ host: 'localhost', port: 8108, protocol: 'http' }]\n  # The API key to use for authentication\n  config.api_key = 'xyz'\n  # The environment you are running in (in Rails, this is set automatically)\n  config.env = 'test'\nend\n```\n\nAlternatively you can configure with env variables:\n\n```env\nTYPESENSUAL_NODES=http://node1:8108,http://node2:8108,http://node3:8108\nTYPESENSUAL_API_KEY=xyz\nTYPESENSUAL_ENV=test\n```\n\n### Creating your first index\n\nOnce the client is configured, you can create your first index. This is done by creating a subclass\nof `Typesensual::Index` and defining your schema and how to load the data. For example, the\nfollowing index might be used to index movies from an ActiveRecord model:\n\n```ruby\n# app/indices/movies_index.rb\nclass MoviesIndex \u003c Typesensual::Index\n  # The schema of the collection\n  schema do\n    enable_nested_fields\n\n    field 'title', type: 'string'\n    field 'release_date\\..*', type: 'int32', facet: true\n    field 'average_rating', type: 'float', facet: true\n    field 'user_count', type: 'int32'\n    field 'genres', type: 'string[]', facet: true\n  end\n\n  def index(ids)\n    Movies.where(id: ids).includes(:genres).find_each do |movie|\n      yield {\n        id: movie.id,\n        title: movie.title,\n        release_date: {\n          year: movie.release_date.year,\n          month: movie.release_date.month,\n          day: movie.release_date.day\n        },\n        average_rating: movie.average_rating,\n        user_count: movie.user_count,\n        genres: movie.genres.map(\u0026:name)\n      }\n    end\n  end\nend\n```\n\n### Integrating with your model\n\nIf you use ActiveRecord, there's a set of premade callbacks you can use:\n\n```ruby\nclass Movie \u003c ApplicationRecord\n  after_commit MoviesIndex.ar_callbacks, on: %i[create update destroy]\nend\n```\n\nYou're free to use these callbacks as-is, or you can use them as a starting point for your own\nintegration. They're just calling `MoviesIndex.index_one` and `MoviesIndex.remove_one` under the\nhood, so you can do the same in your own callbacks or outside of ActiveRecord.\n\n### Loading data into your index\n\nOnce you have defined your index, you can load data into it and update the alias to point to the\nindexed data. Typesensual provides rake tasks for this purpose if you use ActiveRecord:\n\n```console\n$ bundle exec rake typesensual:reindex[MoviesIndex,Movie]\n==\u003e Reindexing Movie into MoviesIndex (Version 1690076097)\n```\n\nOtherwise you can do similar to the following:\n\n```ruby\ncollection = MoviesIndex.create!\ncollection.index_many(Movie.ids, collection: collection)\nMoviesIndex.update_alias(collection)\n```\n\n### Searching your index\n\nNow that you have data in your index, you can search it! Typesensual provides a simple interface for\nthis purpose, including pagination support:\n\n```ruby\nquery = MoviesIndex.search(query: 'Your Name', query_by: 'title')\nquery.per(10).page(2).load\n```\n\nThe full interface for this is documented in the `Search`, `Results`, and `Hit` classes.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports, feature requests, and pull requests are welcome on [our GitHub][github].\n\n[github]: https://github.com/hummingbird-me/typesensual\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License][mit-license].\n\n[mit-license]: https://opensource.org/licenses/MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhummingbird-me%2Ftypesensual","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhummingbird-me%2Ftypesensual","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhummingbird-me%2Ftypesensual/lists"}