Membaca dan menulis file XML

Penting

Fitur ini ada di Pratinjau Publik.

Extensible Markup Language (XML) adalah bahasa markup untuk memformat, menyimpan, dan berbagi data dalam format tekstual. Ini mendefinisikan sekumpulan aturan untuk menserialisasikan data mulai dari dokumen hingga struktur data sewenang-wenang.

Azure Databricks mendukung XML untuk membaca dan menulis dengan Apache Spark, termasuk inferensi dan evolusi skema otomatis, konfigurasi tag baris, validasi XSD, dan ekspresi SQL seperti from_xml. Dukungan XML asli berfungsi dengan Auto Loader, read_files, dan COPY INTO tanpa memerlukan jar eksternal.

Prasyarat

Dukungan format file XML memerlukan Databricks Runtime 14.3 ke atas.

Opsi

.option() Gunakan metode .options() dan DataFrameReader dan DataFrameWriter untuk mengonfigurasi sumber data XML. Untuk daftar lengkap opsi yang didukung, lihat DataFrameReader Opsi XML dan DataFrameWriter opsi XML.

Mengurai rekaman XML

Spesifikasi XML mengamanatkan struktur yang terbentuk dengan baik. Namun, spesifikasi ini tidak secara langsung diterjemahkan ke format tabular. Anda harus menentukan opsi rowTag untuk mengindikasikan elemen XML yang dipetakan ke DataFrameRow. Elemen rowTag menjadi elemen tingkat teratas struct. Elemen anak dari rowTag menjadi field dari struct tingkat teratas.

Anda dapat menentukan skema untuk rekaman ini atau membiarkannya disimpulkan secara otomatis. Karena pengurai hanya memeriksa rowTag elemen, DTD dan entitas eksternal difilter.

Contoh berikut mengilustrasikan inferensi skema dan penguraian file XML menggunakan opsi rowTag yang berbeda:

Phyton

xmlString = """
  <reviews>
    <review id="r001">
      <author>Alice</author>
      <rating>5</rating>
      <comment>Amazing stay, highly recommend!</comment>
    </review>
    <review id="r002">
      <author>Bob</author>
      <rating>4</rating>
      <comment>Great location, very comfortable</comment>
    </review>
  </reviews>"""

xmlPath = "/Volumes/<catalog>/<schema>/<volume>/reviews.xml"
dbutils.fs.put(xmlPath, xmlString, True)

Scala

val xmlString = """
  <reviews>
    <review id="r001">
      <author>Alice</author>
      <rating>5</rating>
      <comment>Amazing stay, highly recommend!</comment>
    </review>
    <review id="r002">
      <author>Bob</author>
      <rating>4</rating>
      <comment>Great location, very comfortable</comment>
    </review>
  </reviews>"""
val xmlPath = "/Volumes/<catalog>/<schema>/<volume>/reviews.xml"
dbutils.fs.put(xmlPath, xmlString)

Baca berkas XML menggunakan opsi rowTag sebagai "reviews":

Phyton

df = spark.read.option("rowTag", "reviews").format("xml").load(xmlPath)
df.printSchema()
df.show(truncate=False)

Scala

val df = spark.read.option("rowTag", "reviews").xml(xmlPath)
df.printSchema()
df.show(truncate=false)

SQL

SELECT * FROM read_files(
  '/Volumes/<catalog>/<schema>/<volume>/reviews.xml',
  format => 'xml',
  rowTag => 'reviews'
)

Keluaran:

root
|-- review: array (nullable = true)
| |-- element: struct (containsNull = true)
| | |-- _id: string (nullable = true)
| | |-- author: string (nullable = true)
| | |-- comment: string (nullable = true)
| | |-- rating: string (nullable = true)

+----------------------------------------------------------------------------------------+
|review                                                                                  |
+----------------------------------------------------------------------------------------+
|[{r001, Alice, Amazing stay, highly recommend!, 5}, {r002, Bob, Great location..., 4}] |
+----------------------------------------------------------------------------------------+

Baca file XML dengan rowTag sebagai "review":

Phyton

df = spark.read.option("rowTag", "review").format("xml").load(xmlPath)
# Infers four top-level fields and parses `review` in separate rows:

Scala

val df = spark.read.option("rowTag", "review").xml(xmlPath)
// Infers four top-level fields and parses `review` in separate rows:

SQL

SELECT * FROM read_files(
  '/Volumes/<catalog>/<schema>/<volume>/reviews.xml',
  format => 'xml',
  rowTag => 'review'
)

Keluaran:

root
|-- _id: string (nullable = true)
|-- author: string (nullable = true)
|-- comment: string (nullable = true)
|-- rating: string (nullable = true)

+----+------+--------------------------------+------+
|_id |author|comment                         |rating|
+----+------+--------------------------------+------+
|r001|Alice |Amazing stay, highly recommend! |5     |
|r002|Bob   |Great location, very comfortable|4     |
+----+------+--------------------------------+------+

Memvalidasi rekaman XML dengan XSD

Anda dapat memvalidasi setiap rekaman XML tingkat baris secara opsional dengan Definisi Skema XML (XSD). File XSD ditentukan dalam opsi rowValidationXSDPath. XSD tidak memengaruhi skema baik yang disediakan maupun yang disimpulkan. Rekaman yang gagal validasi ditandai sebagai "rusak" dan ditangani berdasarkan opsi mode penanganan rekaman yang rusak yang dijelaskan di bagian opsi.

Anda dapat menggunakan XSDToSchema untuk mengekstrak skema Spark DataFrame dari file XSD. Ini hanya mendukung jenis sederhana, kompleks, dan urutan, dan hanya mendukung fungsionalitas XSD dasar.

import org.apache.spark.sql.execution.datasources.xml.XSDToSchema
import org.apache.hadoop.fs.Path

val xsdPath = "/Volumes/<catalog>/<schema>/<volume>/reviews.xsd"
val xsdString = """<?xml version="1.0" encoding="UTF-8" ?>
  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="review">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="author" type="xs:string" />
          <xs:element name="rating" type="xs:integer" />
          <xs:element name="comment" type="xs:string" />
        </xs:sequence>
        <xs:attribute name="id" type="xs:string" use="required" />
      </xs:complexType>
    </xs:element>
  </xs:schema>"""

dbutils.fs.put(xsdPath, xsdString, true)

val schema1 = XSDToSchema.read(xsdString)
val schema2 = XSDToSchema.read(new Path(xsdPath))

Tabel berikut ini memperlihatkan konversi jenis data XSD ke jenis data Spark:

Jenis Data XSD Tipe Data Spark
boolean BooleanType
decimal DecimalType
unsignedLong DecimalType(38, 0)
double DoubleType
float FloatType
byte ByteType
short, unsignedByte ShortType
integer, negativeInteger, nonNegativeInteger, nonPositiveInteger, positiveInteger, unsignedShort IntegerType
long, unsignedInt LongType
date DateType
dateTime TimestampType
Others StringType

Mengurai XML bertumpuk

Data XML dalam kolom bernilai string di DataFrame yang ada dapat diurai dengan schema_of_xml dan from_xml yang mengembalikan skema dan hasil yang diurai sebagai kolom struct baru. Data XML diteruskan sebagai argumen ke schema_of_xml dan from_xml harus menjadi satu catatan XML yang terbentuk dengan baik.

skema_dari_XML

Gunakan schema_of_xml untuk menyimpulkan skema Spark dari string XML. Teruskan hasilnya ke from_xml untuk mengurai kolom XML.

Sintaks: schema_of_xml(xmlStr [, options])

Argument Required Description
xmlStr Yes Ekspresi STRING yang menentukan satu rekaman XML yang terbentuk dengan baik.
options No Direktif MAP<STRING,STRING> yang menentukan harfiah.

Mengembalikan STRING yang memegang definisi struct dengan n bidang string tempat nama kolom berasal dari elemen XML dan nama atribut. Nilai bidang menyimpan jenis SQL yang diformat turunan.

from_xml

Gunakan from_xml untuk mengurai kolom STRING yang berisi rekaman XML ke dalam struktur. Berikan skema langsung atau gunakan hasil dari schema_of_xml.

Sintaks: from_xml(xmlStr, schema [, options])

Argument Required Description
xmlStr Yes Ekspresi STRING yang menentukan satu rekaman XML yang terbentuk dengan baik.
schema Yes Suatu ekspresi STRING atau pemanggilan fungsi schema_of_xml.
options No Direktif MAP<STRING,STRING> yang menentukan harfiah.

Mengembalikan struct dengan nama dan tipe kolom yang sesuai dengan definisi skema. Skema harus didefinisikan sebagai nama kolom dan pasangan jenis data yang dipisahkan koma seperti yang digunakan, misalnya, CREATE TABLE. Sebagian besar opsi yang diperlihatkan di bagian Opsi berlaku dengan pengecualian berikut:

  • rowTag: Karena hanya ada satu catatan XML, rowTag opsi tidak berlaku.
  • mode (default: PERMISSIVE): Memungkinkan mode untuk menangani rekaman yang rusak selama penguraian.
    • PERMISSIVE: Saat menemukan rekaman rusak, menempatkan string yang malformat ke dalam kolom yang dikonfigurasi oleh columnNameOfCorruptRecord, dan menetapkan kolom yang malformat ke null. Untuk menyimpan rekaman yang rusak, Anda dapat mengatur bidang jenis string bernama columnNameOfCorruptRecord dalam skema yang ditentukan pengguna. Jika skema tidak memiliki bidang, maka skema itu akan mengabaikan rekaman yang rusak ketika penguraian. Saat menyimpulkan skema, secara implisit menambahkan bidang columnNameOfCorruptRecord dalam skema output.
    • FAILFAST: Memunculkan pengecualian saat menemukan rekaman yang rusak.

Contoh

Untuk mengurai kolom string XML, gunakan schema_of_xml untuk menyimpulkan skema, lalu berikan ke from_xml:

Phyton

from pyspark.sql.functions import from_xml, schema_of_xml, lit, col

xml_data = """
  <review id="r001">
    <author>Alice</author>
    <rating>5</rating>
    <comment>Amazing stay, highly recommend!</comment>
  </review>
"""

df = spark.createDataFrame([(1, xml_data)], ["review_id", "payload"])
schema = schema_of_xml(df.select("payload").limit(1).collect()[0][0])
parsed = df.withColumn("parsed", from_xml(col("payload"), schema))
parsed.printSchema()
parsed.show()

Scala

import org.apache.spark.sql.functions.{from_xml, schema_of_xml, lit}

val xmlData = """
  <review id="r001">
    <author>Alice</author>
    <rating>5</rating>
    <comment>Amazing stay, highly recommend!</comment>
  </review>""".stripMargin

val df = Seq((1, xmlData)).toDF("review_id", "payload")
val schema = schema_of_xml(xmlData)
val parsed = df.withColumn("parsed", from_xml($"payload", schema))
parsed.printSchema()
parsed.show()

Untuk mengurai XML sebaris di SQL:

SELECT from_xml('
  <review id="r001">
    <author>Alice</author>
    <rating>5</rating>
    <comment>Amazing stay, highly recommend!</comment>
  </review>',
  schema_of_xml('
  <review id="r001">
    <author>Alice</author>
    <rating>5</rating>
    <comment>Amazing stay, highly recommend!</comment>
  </review>')
);

Mengonversi antara struktur XML dan DataFrame

Karena perbedaan struktur antara DataFrame dan XML, ada beberapa aturan konversi dari data XML ke DataFrame dan dari DataFrame ke data XML. Perhatikan bahwa menangani atribut dapat dinonaktifkan dengan opsi excludeAttribute.

Konversi dari XML ke DataFrame

Saat membaca XML, Azure Databricks memetakan elemen dan atribut XML ke bidang DataFrame sesuai dengan aturan berikut.

Atribut dikonversi menjadi bidang dengan awalan judul attributePrefix.

<one myOneAttrib="AAAA">
  <two>two</two>
  <three>three</three>
</one>

Ini menghasilkan skema berikut:

root
|-- _myOneAttrib: string (nullable = true)
|-- two: string (nullable = true)
|-- three: string (nullable = true)

Data karakter dalam elemen yang berisi atribut atau elemen anak diurai ke dalam bidang valueTag. Jika terdapat beberapa kemunculan data karakter, bidang valueTag dikonversi menjadi tipe array.

<one>
  <two myTwoAttrib="BBBBB">two</two>
  some value between elements
  <three>three</three>
  some other value between elements
</one>

Ini menghasilkan skema berikut:

root
 |-- _VALUE: array (nullable = true)
 |    |-- element: string (containsNull = true)
 |-- two: struct (nullable = true)
 |    |-- _VALUE: string (nullable = true)
 |    |-- _myTwoAttrib: string (nullable = true)
 |-- three: string (nullable = true)

Konversi dari DataFrame ke XML

Saat menulis DataFrame ke XML, struktur berlapis tertentu memerlukan penanganan khusus karena perbedaan antara model data DataFrame dan XML.

Jika DataFrame berisi bidang ArrayType yang tipe elemennya juga ArrayType, saat ditulis ke XML, hal itu menghasilkan tingkat penyarangan tambahan yang tidak muncul saat file XML dibaca lalu ditulis kembali. Ini hanya memengaruhi DataFrames yang bersumber di luar XML — membaca dan menulis file XML mempertahankan struktur asli.

Misalnya, DataFrame dengan skema berikut:

|-- a: array (nullable = true)
| |-- element: array (containsNull = true)
| | |-- element: string (containsNull = true)

dan data berikut:

+------------------------------------+
| a|
+------------------------------------+
|[WrappedArray(aa), WrappedArray(bb)]|
+------------------------------------+

menghasilkan output XML berikut:

<a>
  <item>aa</item>
</a>
<a>
  <item>bb</item>
</a>

Nama elemen array yang tidak disebutkan namanya dalam DataFrame ditentukan oleh opsi arrayElementName (Default: item).

Mengaktifkan kolom data yang diselamatkan

Kolom data yang diselamatkan memastikan bahwa Anda tidak pernah kehilangan data selama ETL. Ini menangkap data apa pun yang tidak diurai karena satu atau beberapa bidang dalam rekaman memiliki salah satu masalah berikut:

  • Tidak ada dalam skema yang disediakan.
  • Tidak cocok dengan jenis data skema yang disediakan.
  • Memiliki ketidakcocokan kasus dengan nama bidang dalam skema yang disediakan.

Kolom data yang diselamatkan dikembalikan sebagai dokumen JSON yang berisi kolom yang diselamatkan, dan jalur file sumber rekaman.

Untuk mengaktifkan kolom data yang diselamatkan, atur opsi rescuedDataColumn menjadi nama kolom saat membaca:

Phyton

df = spark.read.option("rescuedDataColumn", "_rescued_data").format("xml").load("/Volumes/<catalog>/<schema>/<volume>/reviews_xml")

Scala

val df = spark.read.option("rescuedDataColumn", "_rescued_data").format("xml").load("/Volumes/<catalog>/<schema>/<volume>/reviews_xml")

SQL

SELECT * FROM read_files(
  '/Volumes/<catalog>/<schema>/<volume>/reviews_xml',
  format => 'xml',
  rowTag => 'review',
  rescuedDataColumn => '_rescued_data'
)

Untuk menghapus jalur file sumber dari kolom data yang diselamatkan, atur:

spark.conf.set("spark.databricks.sql.rescuedDataColumn.filePath.enabled", "false")

Pengurai XML mendukung tiga mode saat mengurai rekaman: PERMISSIVE, , DROPMALFORMEDdan FAILFAST. Saat digunakan bersama rescuedDataColumn, ketidakcocokan tipe data tidak menyebabkan rekaman dihapus dalam mode DROPMALFORMED atau menimbulkan error dalam mode FAILFAST. Hanya catatan yang rusak (XML yang tidak lengkap atau salah format) yang dibuang atau menyebabkan kesalahan.

Menyimpulkan dan mengembangkan skema dengan Auto Loader

Untuk diskusi terperinci tentang topik ini dan opsi yang berlaku, lihat Mengonfigurasi inferensi dan evolusi skema di Auto Loader. Anda dapat mengonfigurasi Auto Loader untuk secara otomatis mendeteksi skema data XML yang dimuat, memungkinkan Anda menginisialisasi tabel tanpa secara eksplisit mendeklarasikan skema data dan mengembangkan skema tabel saat kolom baru diperkenalkan. Ini menghilangkan kebutuhan untuk melacak dan menerapkan perubahan skema secara manual dari waktu ke waktu.

Secara default, inferensi skema Auto Loader berusaha menghindari masalah evolusi skema karena ketidakcocokan jenis. Untuk format yang tidak mengodekan jenis data (JSON, CSV, dan XML), Auto Loader menyimpulkan semua kolom sebagai string, termasuk bidang berlapis dalam file XML. Apache Spark DataFrameReader menggunakan perilaku yang berbeda untuk inferensi skema, memilih jenis data untuk kolom di sumber XML berdasarkan data sampel. Untuk mengaktifkan perilaku ini dengan Auto Loader, atur opsi cloudFiles.inferColumnTypes ke true.

Auto Loader mendeteksi penambahan kolom baru saat memproses data Anda. Saat Auto Loader mendeteksi kolom baru, aliran berhenti dengan UnknownFieldException. Sebelum aliran Anda mengalami kesalahan ini, Auto Loader melakukan inferensi skema pada batch mikro data terbaru dan memperbarui lokasi skema dengan skema terbaru dengan menambahkan kolom baru ke akhir skema. Tipe data kolom yang ada tetap tidak berubah. Auto Loader mendukung mode yang berbeda untuk evolusi skema, yang Anda tetapkan dalam opsi cloudFiles.schemaEvolutionMode.

Anda dapat menggunakan petunjuk skema untuk memberlakukan informasi skema yang Anda ketahui dan harapkan pada skema yang disimpulkan. Ketika Anda tahu bahwa kolom adalah jenis data tertentu, atau jika Anda ingin memilih jenis data yang lebih umum (misalnya, double alih-alih bilangan bulat), Anda dapat memberikan beberapa petunjuk untuk jenis data kolom dalam bentuk string menggunakan sintaks spesifikasi skema SQL. Saat kolom data yang dipulihkan diaktifkan, bidang yang penamaannya berbeda dari skema akan dimuat ke kolom _rescued_data. Anda dapat mengubah perilaku ini dengan mengatur opsi readerCaseSensitive ke false, sehingga Auto Loader membaca data tanpa membedakan huruf besar/kecil.

Usage

Contoh berikut menggunakan himpunan data Wanderbricks untuk menunjukkan membaca dan menulis file XML menggunakan Spark DataFrame API dan SQL.

Baca dan tulis XML

Gunakan DATAFrame API untuk menulis ulasan Wanderbricks ke XML dan membacanya kembali.

Phyton

# Write Wanderbricks reviews to XML
df = spark.read.table("samples.wanderbricks.reviews")
df.write \
  .format("xml") \
  .option("rootTag", "reviews") \
  .option("rowTag", "review") \
  .save("/Volumes/<catalog>/<schema>/<volume>/reviews.xml")

# Read the XML file back
df_read = spark.read \
  .format("xml") \
  .option("rowTag", "review") \
  .load("/Volumes/<catalog>/<schema>/<volume>/reviews.xml")
df_read.show()

Scala

// Write Wanderbricks reviews to XML
val df = spark.read.table("samples.wanderbricks.reviews")
df.write
  .format("xml")
  .option("rootTag", "reviews")
  .option("rowTag", "review")
  .save("/Volumes/<catalog>/<schema>/<volume>/reviews.xml")

// Read the XML file back
val dfRead = spark.read
  .format("xml")
  .option("rowTag", "review")
  .xml("/Volumes/<catalog>/<schema>/<volume>/reviews.xml")
dfRead.show()

R

df <- loadDF("/Volumes/<catalog>/<schema>/<volume>/reviews.xml", source = "xml", rowTag = "review")
saveDF(df, "/Volumes/<catalog>/<schema>/<volume>/newreviews.xml", "xml", "overwrite")

Anda dapat menentukan skema secara manual saat membaca data:

Phyton

from pyspark.sql.types import StructType, StructField, StringType, IntegerType

custom_schema = StructType([
    StructField("_id", StringType(), True),
    StructField("author", StringType(), True),
    StructField("rating", IntegerType(), True),
    StructField("comment", StringType(), True)
])
df = spark.read.options(rowTag='review').xml('/Volumes/<catalog>/<schema>/<volume>/reviews.xml', schema=custom_schema)
df.show()

Scala

import org.apache.spark.sql.types.{StructType, StructField, StringType, IntegerType}

val customSchema = StructType(Array(
  StructField("_id", StringType, nullable = true),
  StructField("author", StringType, nullable = true),
  StructField("rating", IntegerType, nullable = true),
  StructField("comment", StringType, nullable = true)))
val df = spark.read.option("rowTag", "review").schema(customSchema).xml("/Volumes/<catalog>/<schema>/<volume>/reviews.xml")
df.show()

R

customSchema <- structType(
  structField("_id", "string"),
  structField("author", "string"),
  structField("rating", "integer"),
  structField("comment", "string"))

df <- loadDF("/Volumes/<catalog>/<schema>/<volume>/reviews.xml", source = "xml", schema = customSchema, rowTag = "review")
saveDF(df, "/Volumes/<catalog>/<schema>/<volume>/newreviews.xml", "xml", "overwrite")

Membaca dan menulis XML dengan SQL

Gunakan SQL DDL untuk membuat tabel dari file XML. Azure Databricks menyimpulkan jenis kolom secara otomatis.

DROP TABLE IF EXISTS reviews;
CREATE TABLE reviews
USING XML
OPTIONS (path "/Volumes/<catalog>/<schema>/<volume>/reviews.xml", rowTag "review");
SELECT * FROM reviews;

Anda juga dapat menentukan nama dan jenis kolom di DDL. Dalam hal ini, skema tidak disimpulkan secara otomatis.

DROP TABLE IF EXISTS reviews;

CREATE TABLE reviews (_id string, author string, rating integer, comment string)
USING XML
OPTIONS (path "/Volumes/<catalog>/<schema>/<volume>/reviews.xml", rowTag "review");

Memuat XML menggunakan COPY INTO

Gunakan COPY INTO untuk memuat file XML dari penyimpanan cloud ke dalam tabel Delta.

DROP TABLE IF EXISTS reviews;
CREATE TABLE IF NOT EXISTS reviews;

COPY INTO reviews
FROM "/Volumes/<catalog>/<schema>/<volume>/reviews.xml"
FILEFORMAT = XML
FORMAT_OPTIONS ('mergeSchema' = 'true', 'rowTag' = 'review')
COPY_OPTIONS ('mergeSchema' = 'true');

Baca XML dengan validasi baris

rowValidationXSDPath Gunakan opsi untuk memvalidasi setiap baris terhadap skema XSD saat membaca.

Phyton

df = (spark.read
    .format("xml")
    .option("rowTag", "review")
    .option("rowValidationXSDPath", xsdPath)
    .load("/Volumes/<catalog>/<schema>/<volume>/reviews.xml"))
df.printSchema()

Scala

val df = spark.read
  .option("rowTag", "review")
  .option("rowValidationXSDPath", xsdPath)
  .xml("/Volumes/<catalog>/<schema>/<volume>/reviews.xml")
df.printSchema

SQL

SELECT * FROM read_files(
  '/Volumes/<catalog>/<schema>/<volume>/reviews.xml',
  format => 'xml',
  rowTag => 'review',
  rowValidationXSDPath => '/Volumes/<catalog>/<schema>/<volume>/reviews.xsd'
)

Muat XML dengan Auto Loader

Gunakan Auto Loader untuk terus menyerap file XML dari penyimpanan cloud ke dalam tabel Delta dengan inferensi dan evolusi skema otomatis.

Phyton

query = (spark.readStream
  .format("cloudFiles")
  .option("cloudFiles.format", "xml")
  .option("rowTag", "review")
  .option("cloudFiles.inferColumnTypes", True)
  .option("cloudFiles.schemaLocation", schemaPath)
  .option("cloudFiles.schemaEvolutionMode", "rescue")
  .load(inputPath)
  .writeStream
  .option("mergeSchema", "true")
  .option("checkpointLocation", checkPointPath)
  .trigger(availableNow=True)
  .toTable("reviews")
)

Scala

val query = spark.readStream
  .format("cloudFiles")
  .option("cloudFiles.format", "xml")
  .option("rowTag", "review")
  .option("cloudFiles.inferColumnTypes", true)
  .option("cloudFiles.schemaLocation", schemaPath)
  .option("cloudFiles.schemaEvolutionMode", "rescue")
  .load(inputPath)
  .writeStream
  .option("mergeSchema", "true")
  .option("checkpointLocation", checkPointPath)
  .trigger(Trigger.AvailableNow())
  .toTable("reviews")

Sumber Daya Tambahan:

  • Last updated on