added migrations.rst

Author: dvdmgl

docs/index.rst

@@ -6,7 +6,7 @@
 Welcome to django-pg-fts's documentation!
 =========================================
 
-Implementation PostgeSQL for Full Text Search for Django 1.7, taking advantage of new features Migrations and Custom Lookups.
+Implementation PostgeSQL for Full Text Search for django 1.7, taking advantage of new features Migrations and Custom Lookups.
 
 Features:
 ---------
@@ -31,6 +31,7 @@ Contents:
 
    install
    tutorial
+   migrations
    pg_fts
 
 

docs/migrations.rst

@@ -0,0 +1,221 @@
+Migrations
+==========
+
+
+.. important::
+
+    If you're not familiar with django Migrations, please check `Migrations Documentation <https://docs.djangoproject.com/en/1.7/topics/migrations/>`_ 1st.
+
+
+.. important::
+
+    The order of Migrations.operations matters, you can only apply a index to a field if a field exists, if you delete a model/field you should remove any operation first before removing model/field.
+
+
+Creating
+--------
+
+Trigger
+*******
+
+For creating of trigger is provided :class:`~pg_fts.migrations.CreateFTSTriggerOperation`.
+
+``name``
+
+.. attribute:: CreateFTSTriggerOperation.name
+
+Name of the model
+
+``fts_vector``
+
+.. attribute:: CreateFTSTriggerOperation.fts_vector
+
+Name of the :class:`~pg_fts.fields.TSVectorField`
+
+How it works
+++++++++++++
+
+The trigger only updates the :class:`~pg_fts.fields.TSVectorField` if data is changed in the fields that is indexing, with it's weight (default is 'D') and language.
+
+Example for this model::
+
+    class Article(models.Model):
+        title = models.CharField(max_length=255)
+        article = models.TextField()
+        fts = TSVectorField(
+            (('title', 'A'), 'article'),
+            dictionary='portuguese'
+        )
+
+In Migrations::
+
+    class Migration(migrations.Migration)
+        dependencies = [
+            ('article', '00XX_create_fts_field'),
+        ]
+
+        operations = [
+            CreateFTSTriggerOperation(
+                name='Article',
+                fts_vector='fts',
+            ),
+        ]
+
+Will create this trigger:
+
+.. code-block:: sql
+
+    CREATE FUNCTION article_article_fts_update() RETURNS TRIGGER AS $$
+    BEGIN
+        IF TG_OP = 'INSERT' THEN
+            new.fts = setweight(to_tsvector('portuguese', COALESCE(NEW.title, '')), 'A') || setweight(to_tsvector('portuguese', COALESCE(NEW.article, '')), 'D');
+        END IF;
+        IF TG_OP = 'UPDATE' THEN
+            IF NEW.title <> OLD.title OR NEW.article <> OLD.article THEN
+                new.fts = setweight(to_tsvector('portuguese', COALESCE(NEW.title, '')), 'A') || setweight(to_tsvector('portuguese', COALESCE(NEW.article, '')), 'D');
+            END IF;
+        END IF;
+    RETURN NEW;
+    END;
+    $$ LANGUAGE 'plpgsql';
+    CREATE TRIGGER article_article_fts_update BEFORE INSERT OR UPDATE ON article_article
+    FOR EACH ROW EXECUTE PROCEDURE article_article_fts_update();
+
+
+.. important::
+
+    Trigger will only work for future changes, for existing data use :class:`~pg_fts.migrations.UpdateVectorOperation`.
+
+Index
+*****
+
+For creating of indexes is provided :class:`~pg_fts.migrations.CreateFTSIndexOperation`.
+
+``name``
+
+.. attribute:: CreateFTSIndexOperation.name
+
+Name of the model
+
+``fts_vector``
+
+.. attribute:: CreateFTSIndexOperation.fts_vector
+
+Name of the :class:`~pg_fts.fields.TSVectorField`
+
+
+``index``
+
+.. attribute:: CreateFTSIndexOperation.index
+
+Options:
+
+- ``gin`` GIN (Generalized Inverted Index)-based index. Faster to build, slower to lookup.
+
+- ``gist`` GiST (Generalized Search Tree)-based index. Faster to lookup, slower to build.
+
+For information about the ``gin`` and ``gist`` indexes types consult :pg_docs:`PostgreSQL documentation 12.9. GiST and GIN Index Types <textsearch-indexes.html>`
+
+
+Migrating from existing application
+-----------------------------------
+
+For existing application with data is provided :class:`~pg_fts.migrations.UpdateVectorOperation`, this will update the vector.
+
+``name``
+
+.. attribute:: UpdateVectorOperation.name
+
+Name of the model
+
+``fts_vector``
+
+.. attribute:: UpdateVectorOperation.fts_vector
+
+Name of the :class:`~pg_fts.fields.TSVectorField`
+
+
+Changing and Removing
+---------------------
+
+Changing Index
+**************
+
+If you have a existing index created by :class:`~pg_fts.migrations.CreateFTSIndexOperation` of type ``gin`` to migrate for ``gist`` you have to 1st remove the existing index with :class:`~pg_fts.migrations.DeleteFTSIndexOperation` and create a of type ``gist`` with :class:`~pg_fts.migrations.CreateFTSIndexOperation`.
+
+Example::
+
+    class Migration(migrations.Migration)
+        dependencies = [
+            ('article', '0003_fts_create_index_trigger'),
+        ]
+
+        operations = [
+            DeleteFTSIndexOperation(
+                name='Article',
+                fts_vector='fts_index',
+                index='gin'
+            ),
+            CreateFTSIndexOperation(
+                name='Article',
+                fts_vector='fts_index',
+                index='gist'
+            ),
+        ]
+
+Alterations on :class:`~pg_fts.fields.TSVectorField`
+****************************************************
+
+If you change :class:`~pg_fts.fields.TSVectorField` is fields, ranks or dictionary you have to:
+
+1. remove the trigger with :class:`~pg_fts.migrations.DeleteFTSTriggerOperation` and only after you can create
+
+2. a new trigger with :class:`~pg_fts.migrations.CreateFTSTriggerOperation`.
+
+For updating :class:`~pg_fts.fields.TSVectorField` run :class:`~pg_fts.migrations.UpdateVectorOperation`.
+
+.. hint::
+
+    If the fields are the same (fields and rank) but you are updating to multiple dictionaries, for efficiency, keep the previous dictionary as default, as the lexemes and weight will be the same in :class:`~pg_fts.fields.TSVectorField`.
+    There is no need to run :class:`~pg_fts.migrations.UpdateVectorOperation`
+
+Removing Index
+**************
+
+For removing the index is provided :class:`~pg_fts.migrations.DeleteFTSIndexOperation`.
+
+``name``
+
+.. attribute:: DeleteFTSIndexOperation.name
+
+Name of the model
+
+``fts_vector``
+
+.. attribute:: DeleteFTSIndexOperation.fts_vector
+
+Name of the :class:`~pg_fts.fields.TSVectorField`
+
+The previous index type, important for regressions.
+
+``index``
+
+.. attribute:: CreateFTSIndexOperation.index 
+
+
+Removing Trigger
+****************
+
+For removing the index is provided :class:`~pg_fts.migrations.DeleteFTSTriggerOperation`.
+
+``name``
+
+.. attribute:: DeleteFTSTriggerOperation.name
+
+Name of the model
+
+``fts_vector``
+
+.. attribute:: DeleteFTSTriggerOperation.fts_vector
+
+Name of the :class:`~pg_fts.fields.TSVectorField`

docs/pg_fts.rst

@@ -13,7 +13,14 @@ pg_fts.fields module
 pg_fts.aggregates module
 ------------------------
 
-.. automodule:: pg_fts.aggregates 
+.. note::
+    
+    Deprecated use :mod:`pg_fts.ranks` instead.
+
+pg_fts.ranks module
+------------------------
+
+.. automodule:: pg_fts.ranks 
     :members:
 
 

docs/tutorial.rst

@@ -14,7 +14,7 @@ Create a new project like ``fooproject`` and ``article`` app::
 
 **Add ``pg_fts`` To ``INSTALLED_APPS``**
 
-As with most Django applications, you should add ``pg_fts`` to the ``INSTALLED_APPS`` in your ``settings.py`` file::
+As with most django applications, you should add ``pg_fts`` to the ``INSTALLED_APPS`` in your ``settings.py`` file::
 
     INSTALLED_APPS = (
         'django.contrib.auth',
@@ -173,26 +173,26 @@ With ``python manage.py shell``::
     >>> from testapp.models import Article
     >>> Article.objects.create(title='PHP', article='what a pain, the worst of c, c++, perl all mixed in one stupid thing')
     >>> Article.objects.create(title='Python', article='is awesome')
-    >>> Article.objects.create(title='Django', article='is awesome, made in python, multiple databases support, it has a ORM, class based views, template layer')
+    >>> Article.objects.create(title='django', article='is awesome, made in python, multiple databases support, it has a ORM, class based views, template layer')
     >>> Article.objects.create(title='Wordpress', article="what a pain, made in PHP, it's ok if you just add a template and some plugins")
     >>> Article.objects.create(title='Javascript', article='A functional language, with c syntax. The braces nightmare')
     >>> Article.objects.filter(fts_index__search='django')
-    [<Article: Django>]
+    [<Article: django>]
     >>> Article.objects.filter(fts_index__search='Python')
-    [<Article: Python>, <Article: Django>]
+    [<Article: Python>, <Article: django>]
     >>> Article.objects.filter(fts_index__search='templates')
-    [<Article: Wordpress>, <Article: Django>]
+    [<Article: Wordpress>, <Article: django>]
     # postgress & and
     search = Article.objects.filter(fts_index__search='templates awesome')
     >>> print(search.query)
     SELECT "article_article"."id", "article_article"."title", "article_article"."article", "article_article"."fts_index" FROM "article_article" WHERE "article_article"."fts_index" @@ to_tsquery('portuguese', templates & awesome)
     print(search)
-    [<Article: Django>] # only django has template language AND is awesome
+    [<Article: django>] # only django has template language AND is awesome
     isearch = Article.objects.filter(fts_index__isearch='templates awesome')
     >>> print(isearch.query)
     SELECT "article_article"."id", "article_article"."title", "article_article"."article", "article_article"."fts_index" FROM "article_article" WHERE "article_article"."fts_index" @@ to_tsquery('portuguese', templates | awesome)
     print(isearch)
-    [<Article: Python>, <Article: Wordpress>, <Article: Django>]
+    [<Article: Python>, <Article: Wordpress>, <Article: django>]
     # wordpress oh no and in 2nd position, let's rank the results
 
 Ranking results
@@ -205,16 +205,16 @@ For this lets use :class:`~pg_fts.ranks.FTSRank`, :class:`~pg_fts.ranks.FTSRankC
 >>> from pg_fts.ranks import FTSRank, FTSRankCd
 >>> ranks = Article.objects.annotate(rank=FTSRank(fts_index__isearch='templates awesome')).order_by('-rank')
 >>> ranks
-[<Article: Django>, <Article: Python>, <Article: Wordpress>]
+[<Article: django>, <Article: Python>, <Article: Wordpress>]
 # that's better, wordpress has templates, but it's not awesome, but let's check ranks
 >>> [(r.title, r.rank) for r in ranks]
-[('Django', 0.0607927), ('Python', 0.0303964), ('Wordpress', 0.0303964)]
+[('django', 0.0607927), ('Python', 0.0303964), ('Wordpress', 0.0303964)]
 # lucky for python appear before wordpress, let's normalize the results
 >>> ranks_cd = Article.objects.annotate(rank=FTSRankCd(fts_index__isearch='awesome templates', normalization=[16|32])).order_by('-rank')
 >>> [(r.title, r.rank) for r in ranks_cd]
-[('Python', 0.047619), ('Django', 0.0457674), ('Wordpress', 0.0234196)]
+[('Python', 0.047619), ('django', 0.0457674), ('Wordpress', 0.0234196)]
 
-Python and Django are awesome, check the postgres documentation for more about normalization
+Python and django are awesome, check the postgres documentation for more about normalization
 
 Multiple dictionary example
 ---------------------------
@@ -315,13 +315,13 @@ For Portuguese search::
 
 >>> ArticleMulti.objects.create(title='PHP', article='what a pain, the worst of c, c++, perl all mixed in one stupid thing', dictionary='english')
 >>> ArticleMulti.objects.create(title='Python', article='is awesome', dictionary='english')
->>> ArticleMulti.objects.create(title='Django', article='is awesome, made in python', dictionary='english')
+>>> ArticleMulti.objects.create(title='django', article='is awesome, made in python', dictionary='english')
 >>> ArticleMulti.objects.create(title='Wordpress', article="what a pain, made in PHP, it's ok if you just add a template and some plugins")
 >>> ArticleMulti.objects.create(title='Javascript', article='A functional dictionary, with c syntax. The braces nightmare', dictionary='english')
 ## Portuguese
 >>> ArticleMulti.objects.create(title='PHP', article='que dor, o pior do c, c++ e perl tudo junto para ser a coisa mais estupida', dictionary='portuguese')
 >>> ArticleMulti.objects.create(title='Python', article='é Brutal', dictionary='portuguese')
->>> ArticleMulti.objects.create(title='Django', article='é Altamente, feito em python', dictionary='portuguese')
+>>> ArticleMulti.objects.create(title='django', article='é Altamente, feito em python', dictionary='portuguese')
 >>> ArticleMulti.objects.create(title='Wordpress', article="que dor, feito em PHP, não é mau para quem usa os templates e plugins")
 >>> ArticleMulti.objects.create(title='Javascript', article='Uma linguagem funcional, mas tem sintaxe c para confundir. O pesadelo das chavetas', dictionary='portuguese')
 >>> django_pt = ArticleMulti.objects.filter(fts_index__portuguese__search='django', dictionary='portuguese')
@@ -360,8 +360,8 @@ reverse migration to 0001 so does not include ArticleMulti::
 Delete the 0002 migration, remove ArticleMulti from models.py and add / change Article to::
 
     class Article(models.Model):
-    title = models.CharField(max_length=255)
-    article = models.TextField()
+        title = models.CharField(max_length=255)
+        article = models.TextField()
 
     dictionary = models.CharField(
         max_length=15,
@@ -377,11 +377,11 @@ Delete the 0002 migration, remove ArticleMulti from models.py and add / change A
     def __str__(self):
         return self.title
 
-Let Django find the model alterations for us::
+Let django find the model alterations for us::
 
     python manage.py makemigrations article
 
-But we have to edit the migrations 0002 file before applying and add to operations :class:`~pg_fts.migrations.DeleteFTSTriggerOperation` and :class:`~pg_fts.migrations.DeleteFTSIndexOperation` **before** Django auto migrations, and **at the end** of operations the :class:`~pg_fts.migrations.CreateFTSIndexOperation` and :class:`~pg_fts.migrations.CreateFTSTriggerOperation`.
+But we have to edit the migrations 0002 file before applying and add to operations :class:`~pg_fts.migrations.DeleteFTSTriggerOperation` and :class:`~pg_fts.migrations.DeleteFTSIndexOperation` **before** django auto migrations, and **at the end** of operations the :class:`~pg_fts.migrations.CreateFTSIndexOperation` and :class:`~pg_fts.migrations.CreateFTSTriggerOperation`.
 
 The migrations 0002 file should be like this::
 
@@ -414,7 +414,7 @@ The migrations 0002 file should be like this::
                 fts_vector='fts_index',
                 index='gin'
             ),
-            # the Django created changes
+            # the django created changes
             migrations.AddField(
                 model_name='article',
                 name='dictionary',
@@ -444,8 +444,8 @@ The migrations 0002 file should be like this::
 
     Pay special attention to the order of creation and deleting.
 
-    You can only apply :class:`~pg_fts.migrations.CreateFTSIndexOperation` and :class:`~pg_fts.migrations.CreateFTSTriggerOperation` after Django created operations.
+    You can only apply :class:`~pg_fts.migrations.CreateFTSIndexOperation` and :class:`~pg_fts.migrations.CreateFTSTriggerOperation` after django created operations.
 
-    The :class:`~pg_fts.migrations.DeleteFTSTriggerOperation` and :class:`~pg_fts.migrations.DeleteFTSIndexOperation` before Django removing/altering operations
+    The :class:`~pg_fts.migrations.DeleteFTSTriggerOperation` and :class:`~pg_fts.migrations.DeleteFTSIndexOperation` before django removing/altering operations
 
     Not to forget **USE AT YOUR OWN RISK**