Add sort key to example queries (#108)

Each example query now has a sort key, which determines how the example queries are ordered in the `Examples` drop-down menu and for the `examples` command. The default sort key is `~`, which is larger than most characters. Ties are broken by the `id` of the example query, which increases over time (example queries added later get a larger `id). That way, without entering new sort keys, the order is the same as before.

NOTE: The migration file `backend/migrations/0074_...` also contains migrations from earlier commits, which by mistake were not added to the repository. But better late than never.

backend/management/commands/examples.py

@@ -48,11 +48,10 @@ def handle(self, *args, returnLog=False, **options):
         # self.log()
         # self.log(f"Keys of Example table: {Example._meta.fields}")
         result = []
-        for example in Example.objects.all():
-            if example.backend.pk == backend.pk:
-                query_name = example.name
-                query_string = self.normalize_query(example.query)
-                result.append(f"{query_name}\t{query_string}")
+        for example in Example.objects.filter(backend=backend).order_by("sortKey"):
+            query_name = example.name
+            query_string = self.normalize_query(example.query)
+            result.append(f"{query_name}\t{query_string}")
         self.log(f"Returning {len(result)} example queries for backend \"{slug}\"")
         return "\n".join(result) + "\n"
 

backend/migrations/0074_example_sortkey_alter_backend_defaultmodetimeout_and_more.py

@@ -0,0 +1,43 @@
+# Generated by Django 5.0.3 on 2024-10-05 12:26
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('backend', '0073_backend_mapviewbaseurl'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='example',
+            name='sortKey',
+            field=models.CharField(blank=True, default='', help_text='Sort key, according to which examples are ordered lexicographically for a backend', max_length=100, verbose_name='Sort key'),
+        ),
+        migrations.AlterField(
+            model_name='backend',
+            name='defaultModeTimeout',
+            field=models.FloatField(default=0, help_text='Default timeout in seconds for autocompletion queries', verbose_name='Autocomplete timeout'),
+        ),
+        migrations.AlterField(
+            model_name='backend',
+            name='dynamicSuggestions',
+            field=models.IntegerField(choices=[(3, '4. Mixed mode'), (2, '3. SPARQL & context sensitive entities'), (1, '2. SPARQL & context insensitive entities'), (0, '1. SPARQL syntax & keywords only')], default=2, help_text='Default for how to compute autocompletion queries if any', verbose_name='Default autocompletion mode'),
+        ),
+        migrations.AlterField(
+            model_name='backend',
+            name='isDefault',
+            field=models.BooleanField(default=0, help_text='Check if this should be the default backend for the QLever UI', verbose_name='Use as default'),
+        ),
+        migrations.AlterField(
+            model_name='backend',
+            name='isNoSlugMode',
+            field=models.BooleanField(default=0, help_text='Check if this default backend should also be available without a slug in the QLever UI', verbose_name='Enable no-slug mode'),
+        ),
+        migrations.AlterField(
+            model_name='backend',
+            name='mixedModeTimeout',
+            field=models.FloatField(default=1, help_text='Timeout in seconds for the sensitive autocompletion query in mixed mode', verbose_name='Mixed mode timeout'),
+        ),
+    ]

backend/migrations/0075_alter_example_sortkey.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.0.3 on 2024-10-05 13:59
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('backend', '0074_example_sortkey_alter_backend_defaultmodetimeout_and_more'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='example',
+            name='sortKey',
+            field=models.CharField(default='~', help_text="Sort key, according to which example queries are ordered lexicographically; default is '~', which is larger than most characters", max_length=100, verbose_name='Sort key'),
+        ),
+    ]

backend/models.py

@@ -487,6 +487,12 @@ class Example(models.Model):
     name = models.CharField(
         max_length=100, help_text="Name of this example to show in the user interface")
     query = models.TextField()
+    sortKey = models.CharField(
+            max_length=100,
+            default="~",
+            help_text=("Sort key, according to which example queries are ordered lexicographically"
+                       "; default is '~', which is larger than most characters"),
+            verbose_name="Sort key")
 
     def __str__(self):
         return self.name

backend/views.py

@@ -78,8 +78,8 @@ def index(request, backend=None, short=None):
         # safe to session
         request.session['backend'] = activeBackend.pk
 
-        # get examples
-        examples = Example.objects.filter(backend=activeBackend)
+        # Get examples ordered by `sortKey`.
+        examples = Example.objects.filter(backend=activeBackend).order_by("sortKey")
 
     # collect shortlink data
     if short is not None: