From 4d89da97929f8e25cfeba584e66f8cf664e942fc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20Bedn=C3=A1=C5=99?= <jakub.bednar@gmail.com>
Date: Tue, 30 Jun 2026 14:01:59 +0200
Subject: [PATCH] docs: document executable jar service descriptor merging

---
 README.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/README.md b/README.md
index 61c0a964..a2f94be1 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,25 @@ dependencies {
 }
 ```
 
+### Packaging executable JARs
+
+The query API uses gRPC and Apache Arrow Flight. If you package your application
+as a single executable JAR, make sure `META-INF/services` files from dependencies
+are merged instead of overwritten.
+
+Without this, the application can work from an IDE or Maven classpath but fail
+when started with `java -jar` with an error like:
+
+```text
+java.lang.IllegalArgumentException: Address types of NameResolver 'unix' ... not supported by transport
+```
+
+For the Maven Shade Plugin, add `ServicesResourceTransformer`:
+
+```xml
+<transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
+```
+
 ## Usage
 
 ### Create client