Versions Compared

Old Version 3

changes.mady.by.user Sagar Kapare

Saved on

compared with

New Version Current

changes.mady.by.user Sagar Kapare

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This document describes the API for the Field Level Lineage feature. Please see corresponding examples and user stories for more details about the feature.

Platform API

  1. Input to the field operation can be Source (in case of Source plugin) or another field(in case of Transform plugin).

    Code Block
    languagejava
    // Represents input to the Field operations
public abstract class Input {
   // Schema Namefield which is uniquelyinput identifiesto the inputoperation
   StringSchema.Field namefield;
 
   // Description associated with the input Source information if the field belongs to the source/dataset
   @Nullable
   StringSource descriptionsource;
 
   // Create input from thea source datasetField. NoteSince thatSchema thiscan willbe nested, plain String cannot //be always
be dataset as even// forused externalto sourcesuniquely suchidentify asthe Kafka,Field Filein the Schema, as //multiple weFields createcan datasethave forsame lineagename
purpose as identified by// thebut Referencedifferent Namenesting. In order to publicuniquely staticidentify Inputa ofDataset(String name) {
    ...Field from the Schema we will 
   // }need  an enhancement in the publicCDAP staticplatform Inputso ofDataset(String namespace, String name) {
 that each Field can hold the transient
  ... // reference to }the parent Field. From these references, then //we Createcan inputcreate fromunique afield Field. Since Schema can be nested, plain String cannot be path.
   public static Input ofField(Schema.Field field) {
    ...
   }
 
   // usedCreate toinput uniquely identifyfrom the Field inwhich thebelongs Schema,to asthe multipleSource
Fields can have samepublic namestatic Input ofField(Source  // but different nesting. In order to uniquely identify a Field from the Schema we will 
   // need an enhancement in the CDAP platform so that each Field can hold the transientsource, Schema.Field field) {
    ...
   }
}
 
// Represents the Source dataset information.
public class Source {
   // Namespace associated with the Dataset. 
   // referenceThis tois therequired parentsince Field.programs Fromcan theseread references,the thendata wefrom candifferent createnamespace.
unique field path. String namespace;
 
public static Input ofField(Schema.Field field) {
    ...
   }
}
 
// Concrete implementationName of the Inputsource whichdataset
represents the Source publicString class DatasetInput extends Input {name;
 
   // NamespaceProperties associated with the source Datasetdataset. 
   // This iscan requiredpotentially since programs can read the data from different namespace.
   String namespace;
 
   // Properties associated with the Input. 
   // This can potentially store store plugin properties for context.
   // For example in case of KafkaConsumer source, properties can include broker id, list of topics etc.
   Map<String, String> properties;
}
 

  2. Output of field operation can only be field.

    Code Block
    // ConcreteRepresent implementationOutput ofin the Input which represents the Field.field operation
public class FieldInput extends InputOutput {
   Schema.Field field;   
}

  3. Output of field operation can only be field (This is to confirm, otherwise we would need hierarchy similar to the Input side).

    Code Block
    // Represent Output in the field operation
public class Output {
   Schema.Field field;   
}

  4. Field operation consists of one or more Input and Field operation consists of one or more Input and one or more Output along with the name and its description.

    Code Block
    languagejava
    public class FieldOperation {
   // Operation name
   String name;
 
   // Optional detailed description about the operation
   String description;
 
   // Set of input fields participate in the operation 
   Set<Input> inputs;
 
   // Set of output fields generated as a part of this operation
   // Note that this can be null for example in case of "Drop Field" operation.
   // However if the field is dropped and its not present in the destination 
   // dataset it cannot be reached in the lineage graph.
   @Nullable
   Set<Output> outputs;
 
   // Builder for the FieldOperation
   public static Builder {
      String name;
      String description;
      Set<Input> inputs;
      Set<Output> outputs;
 
      private Builder(String name) {
        this.name = name;
        inputs = new HashSet<>();
        outputs = new HashSet<>();
      }
 
      public Builder setDescription(String description) {
         this.description = description;
         return this;
      }
 
      public Builder addInput(Input input) {
         inputs.add(input);
         return this;
      }


      public Builder addInputs(Collection<Input> inputs) {
         this.inputs.addAll(inputs);
         return this;
      }
 
      public Builder addOutput(Output output) {
         outputs.add(output);
         return this;
      }   


      public Builder addOutputs(Collection<Output> outputs) {
         this.outputs.addAll(outputs);
         return this;
      }   
   }       
}

  5. List of field operations can be supplied to the platform through LineageRecorder interface. Program runtime context (such as MapReduceContext) can implement this interface.

    Code Block
    languagejava
    /**
 * This interface provides methods that will allow programs to record the field level operations.
 */
public interface LineageRecorder {
    /**
     * Record the field level operations against the given destination.
     *
     * @param destination the destination for which to record field operations
     * @param fieldOperations The list of field operations.
    */
    void record(Destination destination, List<FieldOperation> fieldOperations);
}


// Destination represents the dataset of which the fields will be part of. 
public class Destination {
   // Namespace associated with the Dataset. 
   // This is required since programs can read the data from different namespace.
   String namespace;
 
   // Name of the Dataset
   String name;
 
   // Description associated with the Dataset.
   String description;
 
   // Properties associated with the Dataset. 
   // This can potentially store plugin properties of the Sink for context.
   // For example in case of KafkaProducer sink, properties can include broker id, list of topics etc.
   Map<String, String> properties;
}

  6. Example usage: Consider a simple MapReduce program which does concatenation of the two fields from the source. The Field level operations emitted would look like below -

    Code Block
    languagejava
    public class NoramlizerMapReduce extends AbstractMapReduce {
public static final Schema OUTPUT_SCHEMA = Schema.recordOf("user", Schema.Field.of("UID", Schema.of(Schema.Type.LONG)),
                                                            Schema.Field.of("Name", Schema.of(Schema.Type.STRING)),
                                                            Schema.Field.of("DOB", Schema.of(Schema.Type.STRING)),
                                                            Schema.Field.of("Zip", Schema.of(Schema.Type.INT)));
...
   public void initialize() throws Exception {
      MapReduceContext context = getContext();
      context.addInput(Input.ofDataset("Users"));
      context.addOutput(Output.ofDataset("NormalizedUserProfiles"));
      DatasetProperties inputProperties = context.getAdmin().getDatasetProperties("Users");
      Schema inputSchema = inputProperties.getProperties().get(DatasetProperties.SCHEMA);
      DatasetProperties outputProperties = context.getAdmin().getDatasetProperties("NormalizedUserProfiles");
      Schema outputSchema = outputProperties.getProperties().get(DatasetProperties.SCHEMA);

      ...
      List<FieldOperation> operations = new ArrayList<>();
      
      FieldOperation.BuilderSource buildersource = new FieldOperation.Source.of("Users");
      FieldOperation.Builder builder = new FieldOperation.Builder("Concat");
      builder
         .setDescription("Concatenating the FirstName and LastName fields to create Name field.")
         .addInput(Input.ofField(source, inputSchema.getField("FirstName")))
         .addInput(Input.ofField(source, inputSchema.getField("LastName")))
         .addOutput(Output.ofField(outputSchema.getField("Name")))
      operations.add(builder.build());


      builder = new FieldOperation.Builder("Drop");
      builder
         .setDescription("deleting the FirstName field")
         .addInput(Input.ofField(source, inputSchema.getField("FirstName")))
      operations.add(builder.build());
 
      builder = new FieldOperation.Builder("Drop");
      builder
         .setDescription("deleting the LastName field")
         .addInput(Input.ofField(source, inputSchema.getField("LastName")))
      operations.add(builder.build());

      context.record(Destination.of("NormalizedUserProfiles"), operations);
      ...   
   }
...
}

  7. For some input datasets (such as Filesets?), DatasetProperties.SCHEMA may not be available since not all datasets have schema associated with it. So the program will have to explicitly create Fields based on the logic of the program. Consider a WordCount MapReduce program which reads lines from the files and create ouput dataset with words and correpsonding counts. We need to create 3 different fields in the program to represent this as shown below -

    Code Block
    languagejava
    public class WordCount extends AbstractMapReduce {

  @Override
  public void initialize() throws Exception {
    MapReduceContext context = getContext();
    Job job = context.getHadoopJob();
    job.setMapperClass(Tokenizer.class);
    job.setReducerClass(Counter.class);
    job.setNumReduceTasks(1);

    String inputDataset = context.getRuntimeArguments().get("input");
    String outputDataset = context.getRuntimeArguments().get("output");
    context.addInput(Input.ofDataset(inputDataset));
    context.addOutput(Output.ofDataset(outputDataset));


    // Create dummy FieldsField for the lineage
    Schema.Field record = Schema.Field.of("record", Schema.of(Schema.Type.String));
 
    // Fields from the output dataset
    Schema.Field word = Schema.Field.of("word", Schema.of(Schema.Type.String));
    Schema.Field count = Schema.Field.of("count", Schema.of(Schema.Type.Long));
    
    Source List<FieldOperation>source operations = new ArrayList<>();= Source.of(inputDataset);  

    List<FieldOperation> operations = new ArrayList<>();
   FieldOperation.Builder builder = new FieldOperation.Builder("ReadCreate");
    builder
      .setDescription("ReadingCreating Word theand inputCount filesfields")
      .addInput(source, Input.ofDatasetofField(inputDatasetrecord))
      .addOutput(record)(Input.ofField(word))
      operations.addaddOutput(builderInput.buildofField(count)); 
    builder = new FieldOperation.Builder("Create"operations.add(builder.build());
    builder
      .setDescription("Creating Word and Count fields")context.record(Destination.of(outputDataset), operations);
      ..addInput(Input.ofField(record))
      .addOutput(Input.ofField(word))}
}

Plugin API

  1. Field level lineage API will not be available to the Source plugins. Data pipeline application can determine the output schema of the Source plugin which is supplied at configure time or runtime as a macro. [TODO: Talked to Albert earlier and few changes required to perform the schema propagation if it is supplied as a part of macro. File a JIRA for this]. Data pipeline application can also know which dataset, the source is reading from. [TODO: File JIRA for this to keep mapping of the stage and dataset in the app]. So for any stage subsequent to the Source, it is possible for app to call the platform with correctly specifying the input fields (combination of Schema.Field and Source).
    1. It is still possible for the source to add additional fields to the output schema, for example, file path in case of the File source plugin. Should file path is also be associated with the Source?

  2. Transform plugins and Sink plugins will be able to provide the field level lineage using following API. This API will be available to the prepareRun method through context.

    Code Block
    languagejava
    public interface LineageRecorder {
   void record(List<FieldOperation> operations);
}

    There are few differences between the FieldOperation class available to the plugins and the one from platform. Mainly the FieldOperation class available to the plugins will not have notion of the Source in it and it will be able to assign the metadata.

    Code Block
    languagejava
    public class Input {
   Schema.Field field;
}
 
public class Output {
   Schema.Field field;
}
 
public class FieldOperation {
   // Operation name
   String name;
 
   // Optional detailed description about the operation
   String description;
 
   // Set of input fields participate in the operation 
   Set<Input> inputs;
 
   // Set of output fields generated as a part of this operation
   // Note that this can be null for example in case of "Drop Field" operation.
   // However if the field is dropped and its not present in the destination 
   // dataset it cannot be reached in the lineage graph.
   @Nullable
   Set<Output> outputs;
 
   // Boolean flag to determine wheteher the metadata from the inputs to outputs is propagated
   boolean propagateMetadata;
 
   // Builder for the FieldOperation
   public static Builder {
      String name;
      String description;
      Set<Input> inputs;
      Set<Output> outputs;
      boolean propagateMetadata;
 
      private Builder(String name) {
        this.name = name;
        inputs = new HashSet<>();
        outputs = new HashSet<>();
      }
 
      public Builder setDescription(String description) {
         this.description = description;
         return this;
      }
 
      public Builder addInput(Input input) {
         inputs.add(input);
         return this;
      }


      public Builder addInputs(Collection<Input> inputs) {
         this.inputs.addAll(inputs);
         return this;
      }
 
      public Builder addOutput(Output output) {
         outputs.add(output);
         return this;
      }   


      public Builder addOutputs(Collection<Output> outputs) {
         this.outputs.addAll(outputs);
         return this;
      }   
 
      public Builder withMetadataPropagationEnabled() {
         .addOutput(Input.ofField(count))this.propagateMetadata = true;
          operations.add(builder.build());return this;
       context.record(Destination.of(outputDataset), operations);
}
   }    ...   }
}
}

    When metadata propagation is enabled during field operation, metadata from the input fields will be propagated to the output fields. We will need to clearly define what happens when the field operation has multiple inputs. Should the output fields get union of metadata? How the conflitcts are resolved then?