SHOW TABLES geeft geen resultaat en de foutmelding vertelt je ook niets nuttigs.
Een Databricks-engineer registreert een Iceberg-tabel in AWS Glue, bevestigt dat de tabel bestaat in de Glue-console, voert SHOW TABLES IN glue_catalog.my_database uit vanuit een Databricks-notebook en krijgt een leeg resultaat terug. Of erger nog: AnalysisException: [TABLE_OR_VIEW_NOT_FOUND]. De tabel bestaat wel. Glue weet ervan. S3 bevat de databestanden en de metadata-directory. Maar Spark kan de tabel niet vinden.
De hoofdoorzaak is bijna altijd een verkeerde configuratie van de Spark-catalogus, maar de foutmelding geeft geen indicatie van welke eigenschap onjuist of ontbrekend is. De catalogus resolutie van Spark behandelt een verkeerd geconfigureerde externe catalogus op dezelfde manier als een catalogus die niet bestaat: er wordt teruggevallen op de standaard spark_catalog, er wordt gezocht in de Hive-metastore of Unity Catalog, er wordt niets gevonden en de tabel wordt als ontbrekend gerapporteerd.
Dit gebeurt omdat Databricks-clusters standaard niet de Iceberg-catalogus klassen op het classpath bevatten. Je koppelt een externe catalogus tijdens runtime via Spark-eigenschappen en een Maven-gecoördineerde JAR. Als een van de onderdelen in die keten niet klopt – verkeerde klassenaam, ontbrekende JAR, geen IAM-beleid – is de foutmelding hetzelfde: er wordt niets gemeld.
De discussie hierover in het Databricks Community-forum leverde zeven reacties op, waarvan de meeste iets andere combinaties van eigenschappen bevatten. Dat patroon alleen al zegt iets: de configuratiemogelijkheden zijn beperkt, maar onvergeeflijk. Er zijn zes eigenschappen die allemaal tegelijk correct moeten zijn, en Spark zal je niet vertellen welke er niet klopt.
De zes eigenschappen van Spark en waarom elk ervan afzonderlijk niet werkt
Hier is de volledige set Spark-configuratie-eigenschappen die nodig zijn om een Iceberg-tabel te lezen via AWS Glue Data Catalog op een Databricks-cluster:
``
spark.sql.extensions = org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions
spark.sql.catalog.glue_catalog = org.apache.iceberg.spark.SparkCatalog
spark.sql.catalog.glue_catalog.catalog-impl = org.apache.iceberg.aws.glue.GlueCatalog
spark.sql.catalog.glue_catalog.warehouse = s3://your-bucket/warehouse/
spark.sql.catalog.glue_catalog.io-impl = org.apache.iceberg.aws.s3.S3FileIO
``
Plus de Iceberg runtime JAR: org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.7.0 (pas het versie-achtervoegsel aan voor je Spark- en Scala-versies).
Elke eigenschap faalt op een andere manier wanneer deze onjuist is. Laat catalog-impl weg en Spark valt terug op een Hadoop-catalogus die rechtstreeks naar metadata zoekt in het pad warehouse, waarbij Glue volledig wordt omzeild. Laat io-impl weg en Iceberg gebruikt standaard HadoopFileIO, wat werkt voor HDFS, maar een java.lang.InstantiationException of stille leesfouten genereert op S3-paden. Stel warehouse in op een S3-pad zonder een schuine streep aan het einde en sommige Iceberg-versies kunnen de metadata-pointer niet oplossen.
De runtime JAR-versie is belangrijker dan je zou denken. Spark 3.5-clusters hebben iceberg-spark-runtime-3.5_2.12 nodig. Gebruik 3.4 en de klassen worden wel geladen, maar de methodesignaturen komen niet overeen, wat resulteert in een NoSuchMethodError tijdens het uitvoeren van een query — niet bij het opstarten van het cluster. Stel de JAR in via het tabblad Bibliotheken van het cluster of een init-script, niet via %pip install, want dan wordt deze niet correct aan het Spark-classpath toegevoegd.
De naam glue_catalog in de eigenschapssleutels is willekeurig — noem hem ice, glue of prod_iceberg. Maar welke naam je ook kiest, elke volgende eigenschap moet hetzelfde voorvoegsel gebruiken. Een typefout in het voorvoegsel (bijv. spark.sql.catalog.glue.catalog-impl in plaats van spark.sql.catalog.glue_catalog.catalog-impl) creëert een tweede, onvolledige catalogus definitie die Spark zonder waarschuwing negeert.
IAM-machtigingen mislukken tijdens het lezen, niet tijdens de catalogus registratie.
Zelfs als alle Spark-eigenschappen correct zijn, zal de query mislukken als de IAM-rol van het Databricks-cluster niet de juiste Glue- en S3-machtigingen heeft. Het misleidende is dat Spark de catalogus succesvol registreert tijdens de sessie-initialisatie. De opdracht SHOW DATABASES IN glue_catalog zou zelfs kunnen werken, omdat het weergeven van databases alleen glue:GetDatabases vereist. De fout komt pas later aan het licht, wanneer je een specifieke tabel probeert te lezen.
Het lezen van een Iceberg-tabel via Glue vereist minimaal: glue:GetTable, glue:GetDatabase, s3:GetObject, s3:ListBucket en s3:GetBucketLocation voor zowel de warehouse-bucket als de daadwerkelijke datalocatie (die kan verschillen als de tabel is aangemaakt met een aangepaste location-eigenschap). Als de tabel partitiespecificaties gebruikt, voeg dan glue:GetPartitions toe.
De foutmeldingen van IAM zijn iets beter dan die van Spark. Je ziet een AccessDeniedException van de Glue SDK of een 403 Forbidden van S3. Deze uitzonderingen worden echter verpakt in een AnalysisException van Spark, en afhankelijk van de Databricks Runtime-versie kan de oorspronkelijke AWS-fout in de notebookuitvoer worden afgekapt. Controleer de logboeken van de Spark-driver (toegankelijk via de Log Delivery van het cluster of de Spark UI) voor de volledige stacktrace.
Een veelvoorkomende fout: het instantieprofiel van het cluster heeft Glue-machtigingen die zijn gekoppeld aan een specifiek AWS-account, maar de Iceberg-tabel verwijst naar een Glue-database die zich over meerdere accounts uitstrekt. Toegang tot Glue over meerdere accounts vereist een resourcebeleid op de doel-Glue-catalogus en de machtiging glue:GetTable in het IAM-beleid van het bronaccount met de ARN van de doel catalogus. Als een van beide ontbreekt, lijkt de tabel niet te bestaan in plaats van dat de toegang is geweigerd.
Test IAM eerst in isolatie voordat je Spark debugt. Voer aws glue get-table --database-name my_db --name my_table uit in een terminal met dezelfde rolreferenties. Als dit de tabelmetadata retourneert, ligt het probleem niet bij IAM.
Het REST-catalogus pad vervangt vijf eigenschappen door één endpoint.
Vanaf 2025 introduceerde AWS het Glue Iceberg REST Catalog-endpoint als onderdeel van Amazon SageMaker Lakehouse. Dit verandert het integratiepatroon aanzienlijk. In plaats van GlueCatalog plus S3FileIO plus een warehouse-pad te configureren, wijst je Spark naar een REST-endpoint dat de catalogus resolutie, de uitgifte van referenties en de configuratie van bestands-I/O aan de serverzijde afhandelt.
De configuratie wordt als volgt ingekort:
``
spark.sql.catalog.glue_rest = org.apache.iceberg.spark.SparkCatalog
spark.sql.catalog.glue_rest.type = rest
spark.sql.catalog.glue_rest.uri = https://glue.us-east-1.amazonaws.com/iceberg
spark.sql.catalog.glue_rest.rest.sigv4-enabled = true
spark.sql.catalog.glue_rest.rest.signing-region = us-east-1
spark.sql.catalog.glue_rest.rest.signing-name = glue
``
Hierdoor worden de eigenschappen catalog-impl, io-impl en warehouse volledig verwijderd. Het REST-endpoint verzorgt de uitgifte van S3-referenties via tijdelijke STS-tokens, waardoor de IAM-rol van het cluster alleen toestemming nodig heeft om de Glue REST API aan te roepen – geen directe S3-toegang tot de gegevensbestanden. Het endpoint retourneert vooraf ondertekende URL's of uitgegeven referenties per tabelbewerking.
Het nadeel: ondersteuning voor de REST-catalogus vereist Iceberg 1.6.0 of later en Databricks Runtime 14.3 of hoger. Oudere clusters kunnen er geen gebruik van maken. Bovendien is het REST-endpoint regiospecifiek – als je Glue-catalogus zich in us-west-2 bevindt, maar je de URI naar us-east-1 verwijst, krijgt je een geldige HTTP-respons met nul tabellen.
Voor teams die al Unity Catalog gebruiken, biedt Databricks een parallelle oplossing: federeer de Glue-catalogus als een externe catalogus in Unity Catalog. Hiermee kunt je Glue-geregistreerde Iceberg-tabellen bevragen met behulp van standaard driedelige namen (glue_federation.database.table) zonder dat je op cluster niveau een Spark-catalogus hoeft te configureren. Unity Catalog verzorgt de catalogus resolutie en governancebeleid wordt overgenomen. Dit vereist Databricks Runtime 16.4 LTS of later en Unity Catalog met ingeschakelde catalogus federatie.
Je Databricks-taak is geslaagd, maar er zijn verouderde Iceberg-metadata gelezen.
Er is een subtielere foutmodus die door geen enkele foutmelding wordt gedetecteerd. Iceberg-tabellen gebruiken een metadatapointer — een metadata-location-eigenschap in de Glue-tabeldefinitie — die verwijst naar het huidige metadata.json-bestand in S3. Wanneer een schrijver (bijvoorbeeld een EMR-taak of een Glue ETL-taak) nieuwe gegevens vastlegt, wordt deze pointer atomisch in Glue bijgewerkt. Maar als je Databricks-taak de catalogus metadata aan het begin van de sessie in de cache opslaat, kan deze gedurende de sessie een verouderde pointer lezen.
Het cachegedrag van de catalogus in Spark is afhankelijk van de eigenschap spark.sql.catalog.glue_catalog.cache-enabled (standaard ingesteld op true) en cache.expiration-interval-ms (standaard ingesteld op 30 seconden in recente Iceberg-versies). Tijdens een langlopende Spark-sessie – een streaming taak of een interactief notebook dat urenlang openstaat – kan de cache verouderde metadata oneindig lang blijven leveren als de vervaldatum verkeerd is geconfigureerd of als de sessie dateert van vóór een schemawijziging in de Iceberg-tabel.
Het resultaat: je Databricks-taak wordt succesvol voltooid, retourneert rijen en registreert geen fouten – maar de gegevens zijn afkomstig van een eerdere momentopname. Downstream-dashboards tonen de cijfers van gisteren. Een stakeholder signaleert de discrepantie om 9 uur 's ochtends. Je controleert de taak logboeken: alles is geslaagd. De pipeline-monitoringtool geeft groen aan. Het probleem is onzichtbaar voor elk systeem dat alleen de exitcodes van de taak controleert.
Dit is waar observability, naast het monitoren van exitcodes, van belang is. MetricSign volgt de output van Databricks-taken ten opzichte van de verwachte actualiteitsperioden en markeert refresh_delayed wanneer de gegevens die een taak produceert niet binnen het verwachte interval zijn gewijzigd – zelfs als de taak zelf succes rapporteert. Voor Iceberg-pipelines waar verouderde metadata-lezingen stilletjes correct ogende resultaten opleveren, is dat signaal van actualiteit het verschil tussen het probleem direct tijdens de data-invoer ontdekken en erover horen van de CFO.
Om operationele problemen met verouderde metadata-lezingen te voorkomen, stelt je cache.expiration-interval-ms in op een waarde die korter is dan het planningsinterval van je pipeline, of schakelt je caching volledig uit voor batch taken met spark.sql.catalog.glue_catalog.cache-enabled=false. Voor streaming taken gebruikt je de refresh()-methode van Iceberg om een herlaadactie van de metadata af te dwingen vóór elke microbatch.
Een configuratiechecklist die daadwerkelijk helpt
Het debuggen van de integratie tussen Iceberg, Glue en Databricks is frustrerend omdat de foutmodi op Spark SQL-niveau niet van elkaar te onderscheiden zijn. Hier is een systematische aanpak die variabelen één voor één uitsluit.
Controleer eerst of het JAR-bestand zich in het classpath bevindt. Voer spark.sparkContext.getConf.get("spark.jars.packages") uit of controleer het tabblad Bibliotheken van het cluster. Het JAR-bestand moet exact overeenkomen met je Spark-hoofd- en subversie. Voor Spark 3.5 op Scala 2.12 is dat org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.7.0 of later.
Controleer vervolgens of de catalogus is geregistreerd. Voer spark.catalog.listCatalogs() uit in een Python-cel of SHOW CATALOGS in SQL. Als glue_catalog (of welke naam je ook hebt gekozen) niet wordt weergegeven, bevat een van de spark.sql.catalog.*-eigenschappen een typefout of is het JAR-bestand niet geladen.
Ten derde, controleer de Glue-connectiviteit onafhankelijk. Voer aws glue get-databases uit met dezelfde IAM-rol als het cluster. Als dit databases retourneert, zijn de Glue-machtigingen in orde. Zo niet, corrigeer dan de IAM-instellingen voordat je Spark aanraakt.
Ten vierde, controleer de indeling van het warehousepad. Het moet een volledige S3-URI zijn met een schuine streep aan het einde: s3://bucket/pad/. Sommige Iceberg-versies accepteren ook s3a://, maar het combineren van s3:// en s3a:// tussen de warehouse-eigenschap en de daadwerkelijke datalocatie van de tabel veroorzaakt problemen met padresolutie.
Ten vijfde, controleer de Spark-driver logboeken op de daadwerkelijke uitzondering. De uitvoer van notebooks kort stacktraces in. Het stderr-logbestand van de driver bevat de volledige GlueException, S3Exception of InstantiationException die Spark in een AnalysisException verpakt. Op Databricks kunt je deze bekijken via de pagina Cluster → tabblad Driver Logs, of je kunt de logboeklevering naar S3/CloudWatch configureren voor permanente toegang.
Als je Databricks Runtime 14.3 of hoger gebruikt in combinatie met Iceberg 1.6 of hoger, kunt je overwegen over te stappen op het REST-catalogus-endpoint of Unity Catalog-federatie. Beide opties vereenvoudigen de configuratie aanzienlijk en elimineren de meest voorkomende configuratiefouten.