{"id":21011067,"url":"https://github.com/ruby-ist/weaviate_record","last_synced_at":"2026-01-06T00:02:48.313Z","repository":{"id":241138773,"uuid":"803354004","full_name":"ruby-ist/weaviate_record","owner":"ruby-ist","description":"An ORM for Weaviate Vector Database","archived":false,"fork":false,"pushed_at":"2024-05-28T15:42:14.000Z","size":70,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-05-29T06:57:47.088Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ruby-ist.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2024-05-20T15:04:21.000Z","updated_at":"2024-05-31T10:41:19.671Z","dependencies_parsed_at":"2024-05-22T16:46:44.541Z","dependency_job_id":"56417848-4456-43e5-848f-1a841bf8c222","html_url":"https://github.com/ruby-ist/weaviate_record","commit_stats":null,"previous_names":["ruby-ist/weaviate_record"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruby-ist%2Fweaviate_record","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruby-ist%2Fweaviate_record/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruby-ist%2Fweaviate_record/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruby-ist%2Fweaviate_record/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ruby-ist","download_url":"https://codeload.github.com/ruby-ist/weaviate_record/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245302552,"owners_count":20593401,"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":[],"created_at":"2024-11-19T09:25:27.497Z","updated_at":"2026-01-06T00:02:48.306Z","avatar_url":"https://github.com/ruby-ist.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"## WeaviateRecord\n\n![Tests status](https://github.com/ruby-ist/weaviate_record/actions/workflows/gem-push.yml/badge.svg)\n![Gem Version](https://badge.fury.io/rb/weaviate_record.svg)\n[![Docs](http://img.shields.io/badge/yard-docs-chartreuse.svg)](http://rubydoc.info/gems/weaviate_record)\n[![License](https://img.shields.io/badge/license-MIT-limegreen.svg)](https://github.com/ruby-ist/weaviate_record/blob/main/LICENSE.txt)\n\nAn ORM for `Weaviate` vector database that follows the same conventions as the `ActiveRecord` and brings the power of Vector database and Retrieval augmented generation (RAG) to your Ruby application.\n\nThis gem uses [weaviate-ruby](https://github.com/patterns-ai-core/weaviate-ruby) internally to connect with `Weaviate` DB.\n\n### Installation\n\n```bash\ngem install weaviate_record\n```\n\nOr you can add it your `Gemfile` with:\n\n```bash\nbundle add weaviate_record\n```\n\n### Prerequisites\n\n`WeaviateRecord` needs a weaviate database running in your local machine or cloud. For creating an weaviate instance on your local machine, please use weaviate's official [configurator](https://weaviate.io/developers/weaviate/installation/docker-compose#configurator).\n\nAfter creating an instance, set an env variable `WEAVIATE_DATABASE_URL` with the database url. If you have authentication enabled on weaviate, set the API key to `WEAVIATE_API_KEY`.\n\nIf you want to use different vectorizer module instead of transformers, please set the env variable `WEAVIATE_VECTORIZER_MODULE` to your model and `WEAVIATE_VECTORIZER_API_KEY` to your module's API key.\n\n### Configuration\n\nYou can configure the `WeaviateRecord` gem by creating an initializer or setup file with following code:\n\n```ruby\nWeaviateRecord.configure do |config|\n\n  # Sync the local schema with actual schema whenever this file is loaded if this value is set to true\n  # Default value: false\n  config.sync_schema_on_load = true\n\n  # Threshold for similarity searches\n  # Default value: 0.55\n  config.similarity_search_threshold = 1.0\n\n  # The file path where WeaviateRecord stores the local copy of your Weaviate database schema.\n  # If Rails is installed in your project, the default value is \"#{Rails.root}/db/weaviate/schema.rb\"\n  # Otherwise, the default value is \"#{Dir.pwd}/db/weaviate/schema.rb\"\n  config.schema_file_path = \"#{Rails.root}/db/weaviate/schema.rb\"\n\nend\n```\n\n### Creating Collection in Weaviate\n\n`WeaviateRecord` does not have a separate DSL for creating collection like `ActiveRecord`. However there are two things you have to keep in mind while creating a collection.\n\n1. you should add [indexTimestamps](https://weaviate.io/developers/weaviate/config-refs/schema#invertedindexconfig--indextimestamps) and [indexNullState](https://weaviate.io/developers/weaviate/config-refs/schema#invertedindexconfig--indexnullstate) to your collection schema. Otherwise, timestamps and null based conditions won't work.\n\n```ruby\nWeaviateRecord::Connection.new.client.create(\n  class_name: 'Article',\n  properties: [...],\n  inverted_index_config: {\n    \"indexNullState\": true,\n    \"indexTimestamps\": true\n  }\n)\n```\n\nNote: You can create a new `Weaviate::Client` instance by calling `#client` method on any `WeaviateRecord::Connection` instances. These object will automatically use the values you assigned on env variables.\n\n2. Wherever you are modifying `Weaviate` schema, be it in rake or migration, or any other file, be sure to call the method `WeaviateRecord::Schema.update!`. It will automatically update your local copy of the database schema.\n\n### Usage\n\nTo use the `WeaviateRecord` for your model, simply inherit the base class.\n`WeaviateRecord` mixins `ActiveModel::Validations`, so you can also add validations as you do for `ActiveRecord` models.\n\n```ruby\nclass Article \u003c WeaviateRecord::Base\n  validate :title, presence: true\n\nend\n```\n\nAnd that's all. Now, you can create and modify `weaviate` records as you do in the `ActiveRecord`. The syntax is exactly same with few naunces.\n\nBelow are all the basic methods defined for CRUD operations. Their syntax and their behaviour is same as their `ActiveRecord` equivalent\n\n- [new](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FBase:initialize)\n- [create](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FBase%2Ecreate)\n- [save](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FBase:save)\n- [find](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FBase%2Efind)\n- [update](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FBase:update)\n- [destroy](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FBase:destroy)\n- [count](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FBase%2Ecount)\n- [persisted?](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FBase:persisted%3F)\n\nFor batch operations,\n\n- [destory_all](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FRelation:destroy_all) (Needs atleast one where condition)\n\nFor query interface, we have\n\n- [select](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FQueries%2FSelect:select)\n- [where](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FQueries%2FWhere:where)\n- [order](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FQueries%2FOrder:order)\n- [limit](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FQueries%2FLimit:limit)\n- [offset](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FQueries%2FOffset:offset)\n\nFor debugging purposes, there is one method called [#to_query](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FRelation%2FQueryBuilder:to_query) which behaves likes `#to_sql` in `ActiveRecord`.\n\nAll the above methods work exactly the same way those `ActiveRecord` methods do. Apart from these, all the methods comes from `ActiveModel::Validations` and `Enumerable` modules are also available, and then there are few other methods where `Weaviate` truly shines.\n\n#### Keyword Search\n\nTo use the weaviate's special keyword based search on your model, there is one method called [#bm25](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FQueries%2FBm25:bm25). There are some limitations you might be facing while using `#bm25`. Notable one is that you cannot chain `#count` or `#order` method with `#bm25`.\n\n```ruby\nArticle.bm25('keyword').count # bm25 will be ignored here\nArticle.bm25('keyword').order # order will be ignored here\n```\n\nThere are some scenarios where `bm25` search does overfitting. To mitigate that, you can query the meta attribute `score` along with the search and filter them once again for relevance.\n\n```ruby\nArticle.select(_additional: :score).bm25('You Keyword').take_while do |article|\n  article.score \u003e= KEYWORD_SEARCH_THRESHOLD\nend\n```\n\n#### Similarity Search\n\nWeaviate offers similarity or vector based search in three ways. You can do it with text, vector or object. Similarily, `WeaviateRecord` comes with three methods.\n\n- [near_text](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FQueries%2FNearText:near_text)\n- [near_vector](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FQueries%2FNearVector:near_vector)\n- [near_object](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FQueries%2FNearObject:near_object)\n\nIt is important to specify the threshold distance whenever you are using similarity search. Otherwise, you search will not be much relevant. You can do it by either passing `distance` parameter to the search or by setting the default value for all three searches in the config.\n\n### QnA Transformers - `#ask` and `#answer`\n\nIf you have enabled `QnA Transformers` in your weaviate database, you can use the [#ask](https://rubydoc.info/gems/weaviate_record/WeaviateRecord%2FQueries%2FAsk:ask) method and get an `answer` attribute like this:\n\n```ruby\nArticle.create(content: \"I'm Barney Stinson. You can call me Legendary\")\n\nArticle.ask('who is he').select(_additional: { answer: :result }).first.answer\n# =\u003e {\"result\"=\u003e\"barney stinson\"}\n```\n\nAnd just like that, you can easily brings the `RAG` to you Ruby application.\n\n### Summarizer - `#summary`\n\nIf you have enabled `Sum Transformers` in your weaviate database, you can summarize the attribute holding the large text like movie review or article summary. Summarizer don't have its own method for now. However, you can call it by doing little work around on `#select` method.\n\n```ruby\ncontent = \u003c\u003c~TEXT\n  Ruby on Rails (simplified as Rails) is a server-side web application framework written in Ruby under the MIT License.\n  Rails is a model–view–controller (MVC) framework, providing default structures for a database, a web service, and web pages.\n  It encourages and facilitates the use of web standards such as JSON or XML for data transfer and HTML, CSS and JavaScript for user interfacing.\n  In addition to MVC, Rails emphasizes the use of other well-known software engineering patterns and paradigms, including convention over configuration (CoC), don't repeat yourself (DRY), and the active record pattern.\nTEXT\narticle = Article.create(content: content)\n\nresults = Article.where(id: article.id)\n                 .select(_additional: 'summary(properties: [\"content\"]) { result }')\n                 .first.summary\n\nputs results\n```\n\nOutput:\n\n```ruby\n[{\"result\"=\u003e\n   \"Rails is a server-side web application framework written in Ruby under the MIT License. It is a model–view–controller (MVC) framework, providing default structures for a database, a web service, and web pages. It encourages and facilitates the use of web standards such as HTML, CSS and JavaScript.\"}]\n```\n\n#### Limitations\n\n`WeaviateRecord` is not yet fully featured ORM like `ActiveRecord`. It doesn't support association, DSL or way to write and handle migrations yet.\n\n#### Support\n\nFeel free to open an issue or PR if you notice any feature is missing or wrong. Happy coding 🎉\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruby-ist%2Fweaviate_record","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruby-ist%2Fweaviate_record","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruby-ist%2Fweaviate_record/lists"}